Skip to content

MySQL Client

Overview⚓︎

You can connect to and execute queries on your Hydrolix cluster using a MySQL client. The Clickhouse MySQL interface provides support for the MySQL protocol and dialect.

Clients may authenticate with credentials or present an authorization token.

Connect to a Hydrolix cluster⚓︎

By default, Hydrolix clusters listen on port 9004 for MySQL TCP connections.

If you have a MySQL client installed, you can test connecting to your Hydrolix cluster using the following command:

1
mysql --protocol tcp -h $HDX_HOST -P 9004 -u $USERNAME --password=$PASSWORD

If your cluster is TLS enabled, then the MySQL server is also TLS enabled and will require TLS for all clients.

You can supply the setting --ssl-mode=REQUIRED to prevent the MySQL client from attempting to connect to a server via plaintext.

1
mysql --ssl-mode=REQUIRED --protocol tcp -h $HDX_HOST -P 9004 -u $USERNAME --password=$PASSWORD

Authenticate with credentials⚓︎

If the credentials are valid, the MySQL server starts an interactive session

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
$ mysql --host {myhost}.hydrolix.live --user "$HDX_USERNAME" --port 9004 --password="$HDX_PASSWORD"
mysql: [Warning] Using a password on the command line interface can be insecure.
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 16
Server version: 24.8.6.1-ClickHouse 

Copyright (c) 2000, 2025, Oracle and/or its affiliates.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>

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

1
2
3
$ mysql --host {myhost}.hydrolix.live --user "$HDX_USERNAME" --port 9004  --password="incorrect-password"
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR 516 (00000): Address: 10.2.4.74:51994 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"}>>

Present an authorization token⚓︎

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

The auth token is communicated over the MySQL 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 MySQL server starts an interactive session.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
$ mysql --host {myhost}.hydrolix.live --user '__api_token__' --port 9004  --password="$HDX_TOKEN"
mysql: [Warning] Using a password on the command line interface can be insecure.
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 15
Server version: 24.8.6.1-ClickHouse 

Copyright (c) 2000, 2025, Oracle and/or its affiliates.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>

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

1
2
3
$ mysql --host {myhost}.hydrolix.live --user '__api_token__' --port 9004  --password="invalid_token"
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR 516 (00000): username@example.com: Authentication failed: password is incorrect, or there is no user with such name.

Tunables⚓︎

You can use the following tunables to enable/disable query forwarding, modify which port accepts MySQL queries, and to enable/disable TLS.

Name Description Type Default
disable_traefik_mysql_port When set to true, the load balancer won't forward queries to Traefik on the default Clickhouse MySQL interface port 9004. boolean false
mysql_port The port to serve the Clickhouse MySQL interface on if applicable. integer 9004
mysql_port_disable_tls TLS is enabled by default. To allow plaintext MySQL connections, set this to true. boolean false

See the Hydrolix Tunables page to read more about tunables and how to use them.

Compatible query tools⚓︎

The following Business Intelligence tools are tested with the Clickhouse MySQL interface:

Limitations⚓︎

  • The MySQL query interface may not support all MySQL language features. The interface is a proxy that converts SQL queries using the MySQL dialect into equivalent ClickHouse queries. A particular query may require dialect features (for example, MySQL-specific functions or settings) that aren't implemented in Clickhouse.