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.

Connecting 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:

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.

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

$ 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.

$ 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 '[email protected]' due to <TurbineApiAuthenticatorError api login failed with provided username/password '[email protected]'. <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:

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.

$ 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.

$ 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): [email protected]: 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.