ClickHouse Connect driver API

### HTTPS/TLS arguments[​](#httpstls-arguments "Direct link to HTTPS/TLS arguments")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Default Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | verify bool True Validate the ClickHouse server TLS/SSL certificate (hostname, expiration, etc.) if using HTTPS/TLS.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | ca\_cert str *None* If *verify*=*True*, the file path to Certificate Authority root to validate ClickHouse server certificate, in .pem format. Ignored if verify is False. This isn't necessary if the ClickHouse server certificate is a globally trusted root as verified by the operating system.| client\_cert str *None* File path to a TLS Client certificate in .pem format (for mutual TLS authentication). The file should contain a full certificate chain, including any intermediate certificates.|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | client\_cert\_key str *None* File path to the private key for the Client Certificate. Required if the private key isn't included the Client Certificate key file.|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | server\_host\_name str *None* The ClickHouse server hostname as identified by the CN or SNI of its TLS certificate. Set this to avoid SSL errors when connecting through a proxy or tunnel with a different hostname|  |  |  |  | | --- | --- | --- | --- | | tls\_mode str *None* Controls advanced TLS behavior. `proxy` and `strict` don't invoke ClickHouse mutual TLS connection, but do send client cert and key. `mutual` assumes ClickHouse mutual TLS auth with a client certificate. *None*/default behavior is `mutual` | | | | | | | | | | | | | | | | | | | | | | | | | | | |

### Settings argument[​](#settings-argument "Direct link to Settings argument")

Finally, the `settings` argument to `get_client` is used to pass additional ClickHouse settings to the server for each client request. Note that in most cases, users with *readonly*=*1* access can't alter settings sent with a query, so ClickHouse Connect will drop such settings in the final request and log a warning. The following settings apply only to HTTP queries/sessions used by ClickHouse Connect, and aren't documented as general ClickHouse settings.

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Setting Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | buffer\_size Buffer size (in bytes) used by the ClickHouse server before writing to the HTTP channel.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | session\_id A unique session ID to associate related queries on the server. Required for temporary tables.|  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | compress Whether the ClickHouse server should compress the POST response data. This setting should only be used for "raw" queries.|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | decompress Whether the data sent to the ClickHouse server must be decompressed. This setting should only be used for "raw" inserts.|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | quota\_key The quota key associated with this request. See the ClickHouse server documentation on quotas.|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | session\_check Used to check the session status.|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | session\_timeout Number of seconds of inactivity before the session identified by the session ID will time out and no longer be considered valid. Defaults to 60 seconds.|  |  |  |  | | --- | --- | --- | --- | | wait\_end\_of\_query Buffers the entire response on the ClickHouse server. This setting is required to return summary information, and is set automatically on non-streaming queries.|  |  | | --- | --- | | role ClickHouse role to be used for the session. Valid transport setting that can be included in query context. | | | | | | | | | | | | | | | | | | | |

For other ClickHouse settings that can be sent with each query, see [the ClickHouse documentation](/docs/operations/settings/settings).

### Client creation examples[​](#client-creation-examples "Direct link to Client creation examples")

- Without any parameters, a ClickHouse Connect client will connect to the default HTTP port on `localhost` with the default user and no password:

```
import clickhouse_connect

client = clickhouse_connect.get_client()
print(client.server_version)
# Output: '22.10.1.98'
```

- Connecting to a secure (HTTPS) external ClickHouse server

```
import clickhouse_connect

client = clickhouse_connect.get_client(host='play.clickhouse.com', secure=True, port=443, user='play', password='clickhouse')
print(client.command('SELECT timezone()'))
# Output: 'Etc/UTC'
```

- Connecting with a session ID and other custom connection parameters and ClickHouse settings.

```
import clickhouse_connect

client = clickhouse_connect.get_client(
    host='play.clickhouse.com',
    user='play',
    password='clickhouse',
    port=443,
    session_id='example_session_1',
    connect_timeout=15,
    database='github',
    settings={'distributed_ddl_task_timeout':300},
)
print(client.database)
# Output: 'github'
```

## Client Lifecycle and Best Practices[​](#client-lifecycle-and-best-practices "Direct link to Client Lifecycle and Best Practices")

Creating a ClickHouse Connect client is an expensive operation that involves establishing a connection, retrieving server metadata, and initializing settings. Follow these best practices for optimal performance:

### Core principles[​](#core-principles "Direct link to Core principles")

- **Reuse clients**: Create clients once at application startup and reuse them throughout the application lifetime
- **Avoid frequent creation**: Don't create a new client for each query or request (this wastes hundreds of milliseconds per operation)
- **Clean up properly**: Always close clients when shutting down to release connection pool resources
- **Share when possible**: A single client can handle many concurrent queries through its connection pool (see threading notes below)

### Basic patterns[​](#basic-patterns "Direct link to Basic patterns")

**✅ Good: Reuse a single client**

```
import clickhouse_connect

# Create once at startup
client = clickhouse_connect.get_client(host='my-host', username='default', password='password')

# Reuse for all queries
for i in range(1000):
    result = client.query('SELECT count() FROM users')

# Close on shutdown
client.close()
```

**❌ Bad: Creating clients repeatedly**

```
# BAD: Creates 1000 clients with expensive initialization overhead
for i in range(1000):
    client = clickhouse_connect.get_client(host='my-host', username='default', password='password')
    result = client.query('SELECT count() FROM users')
    client.close()
```

### Multi-threaded applications[​](#multi-threaded-applications "Direct link to Multi-threaded applications")

Note