Introduction

¹ClickHouse Connect has been explicitly tested against the listed platforms. In addition, untested binary wheels (with C optimization) are built for all architectures supported by the excellent [`cibuildwheel`](https://cibuildwheel.readthedocs.io/en/stable/) project. Finally, because ClickHouse Connect can also run as pure Python, the source installation should work on any recent Python installation.

²SQLAlchemy support is limited to Core functionality (queries, basic DDL). ORM features aren't supported. See [SQLAlchemy Integration Support](/docs/integrations/language-clients/python/sqlalchemy) docs for details.

³ClickHouse Connect generally works well with versions outside the officially supported range.

## Installation[​](#installation "Direct link to Installation")

Install ClickHouse Connect from [PyPI](https://pypi.org/project/clickhouse-connect/) via pip:

`pip install clickhouse-connect`

ClickHouse Connect can also be installed from source:

- `git clone` the [GitHub repository](https://github.com/ClickHouse/clickhouse-connect).
- (Optional) run `pip install cython` to build and enable the C/Cython optimizations
- `cd` to the project root directory and run `pip install .`

## Support policy[​](#support-policy "Direct link to Support policy")

Please update to the latest version of ClickHouse Connect before reporting any issues. Issues should be filed in the [GitHub project](https://github.com/ClickHouse/clickhouse-connect/issues). Future releases of ClickHouse Connect are intended be compatible with actively supported ClickHouse versions at the time of release. Actively supported versions of ClickHouse server can be found [here](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md). If you're unsure what version of ClickHouse server to use, read this discussion [here](https://clickhouse.com/docs/knowledgebase/production#how-to-choose-between-clickhouse-releases). Our CI test matrix tests against the latest two LTS releases and the latest three stable releases. However, due to the HTTP protocol and minimal breaking changes between ClickHouse releases, ClickHouse Connect generally works well with server versions outside the officially supported range, though compatibility with certain advanced data types may vary.

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

### Gather your connection details[​](#gather-your-connection-details "Direct link to Gather your connection details")

To connect to ClickHouse with HTTP(S) you need this information:

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter(s) Description|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `HOST` and `PORT` Typically, the port is 8443 when using TLS or 8123 when not using TLS.|  |  |  |  | | --- | --- | --- | --- | | `DATABASE NAME` Out of the box, there is a database named `default`, use the name of the database that you want to connect to.| `USERNAME` and `PASSWORD` Out of the box, the username is `default`. Use the username appropriate for your use case. | | | | | | | |

The details for your ClickHouse Cloud service are available in the ClickHouse Cloud console.
Select a service and click **Connect**:

Choose **HTTPS**. Connection details are displayed in an example `curl` command.

If you're using self-managed ClickHouse, the connection details are set by your ClickHouse administrator.

### Establish a connection[​](#establish-a-connection "Direct link to Establish a connection")

There are two examples shown for connecting to ClickHouse:

- Connecting to a ClickHouse server on localhost.
- Connecting to a ClickHouse Cloud service.

#### Use a ClickHouse Connect client instance to connect to a ClickHouse server on localhost:[​](#use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-server-on-localhost "Direct link to Use a ClickHouse Connect client instance to connect to a ClickHouse server on localhost:")

```
import clickhouse_connect

client = clickhouse_connect.get_client(host='localhost', username='default', password='password')
```

#### Use a ClickHouse Connect client instance to connect to a ClickHouse Cloud service:[​](#use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-cloud-service "Direct link to Use a ClickHouse Connect client instance to connect to a ClickHouse Cloud service:")

Tip

Use the connection details gathered earlier. ClickHouse Cloud services require TLS, so use port 8443.

```
import clickhouse_connect

client = clickhouse_connect.get_client(host='HOSTNAME.clickhouse.cloud', port=8443, username='default', password='your password')
```

### Interact with your database[​](#interact-with-your-database "Direct link to Interact with your database")

To run a ClickHouse SQL command, use the client `command` method:

```
client.command('CREATE TABLE new_table (key UInt32, value String, metric Float64) ENGINE MergeTree ORDER BY key')
```

To insert batch data, use the client `insert` method with a two-dimensional array of rows and values:

```
row1 = [1000, 'String Value 1000', 5.233]
row2 = [2000, 'String Value 2000', -107.04]
data = [row1, row2]
client.insert('new_table', data, column_names=['key', 'value', 'metric'])
```

To retrieve data using ClickHouse SQL, use the client `query` method:

```
result = client.query('SELECT max(key), avg(metric) FROM new_table')
print(result.result_rows)
# Output: [(2000, -50.9035)]
```

- [Requirements and compatibility](#requirements-and-compatibility)- [Installation](#installation)- [Support policy](#support-policy)- [Basic usage](#basic-usage)
        - [Gather your connection details](#gather-your-connection-details)- [Establish a connection](#establish-a-connection)- [Interact with your database](#interact-with-your-database)

Was this page helpful?