# ClickHouse HTTP Driver (`clickhouse-driver-http`)
Lightweight Python HTTP client for ClickHouse with minimal dependencies.
## Installation
```bash
pip install clickhouse-driver-http
```
## Quick Start
```python
from clickhouse_driver_http import ClickHouseHTTP
# Initialize client (supports both int/string ports)
client = ClickHouseHTTP(
host="localhost", # Required
port=8123, # Default: 8123 (can be string "8123")
username="default", # Default: "default"
password="", # Default: ""
database="default", # Default: "default"
timeout=300, # Default: 300s
max_retries=3, # Default: 3
compression=False # Default: False
)
# Execute query (returns raw tuples)
result = client.execute("SELECT now() AS current_time, version()")
# Get DataFrame (pandas required)
df = client.query_to_df("""
SELECT table, engine
FROM system.tables
WHERE database = currentDatabase()
LIMIT 5
""")
```
## Key Features
- **HTTP Interface** - No native protocol dependency
- **External Tables** - Pass data directly in queries
- **Smart Batching** - Automatic chunking for large results
- **Error Resilient** - Built-in retry mechanism
- **Pandas Support** - Direct DataFrame conversion
## Advanced Examples
### External Tables
```python
data = {
'users': [
{'user_id': 1, 'name': 'Alice'},
{'user_id': 2, 'name': 'Bob'}
]
}
external = [{
'name': 'ext_users',
'structure': [('user_id', 'UInt32'), ('name', 'String')],
'data': data['users']
}]
df = client.query_to_df("""
SELECT u.name, count() as logins
FROM ext_users u
JOIN system.query_log q ON q.user = u.name
GROUP BY u.name
""", external_tables=external)
```
### Batch Processing
```python
# Processes in 100k row batches with auto-retry
large_df = client.query_to_df(
"SELECT * FROM billion_row_table",
batch_size=100000, # Initial batch size
memory_safe=True # Enables memory limits
)
```
## Configuration Reference
| Parameter | Type | Default | Description |
|-----------------|------------|-------------|--------------------------------------|
| `host` | str | - | Server hostname or IP |
| `port` | int/str | 8123 | HTTP interface port |
| `username` | str | "default" | Authentication username |
| `password` | str | "" | Authentication password |
| `database` | str | "default" | Default database context |
| `timeout` | int | 300 | Query timeout in seconds |
| `max_retries` | int | 3 | Connection retry attempts |
| `compression` | bool | False | Enable gzip/deflate compression |
| `verify_ssl` | bool | True | Verify SSL certificates |
## License
MIT License - See [LICENSE](LICENSE) for full text.
> **Note**: Requires Python 3.7+ and `requests` package. Pandas needed for DataFrame support.
Raw data
{
"_id": null,
"home_page": null,
"name": "clickhouse-driver-http",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "clickhouse, http, driver, database",
"author": "Nikita Krachkovskiy",
"author_email": "sudokns@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/20/98/57c23523539e377714c898c0561b389c0baa024f8411d15cc47d980abe20/clickhouse-driver-http-0.1.6.tar.gz",
"platform": null,
"description": "# ClickHouse HTTP Driver (`clickhouse-driver-http`)\n\nLightweight Python HTTP client for ClickHouse with minimal dependencies.\n\n## Installation\n```bash\npip install clickhouse-driver-http\n```\n\n## Quick Start\n```python\nfrom clickhouse_driver_http import ClickHouseHTTP\n\n# Initialize client (supports both int/string ports)\nclient = ClickHouseHTTP(\n host=\"localhost\", # Required\n port=8123, # Default: 8123 (can be string \"8123\")\n username=\"default\", # Default: \"default\"\n password=\"\", # Default: \"\"\n database=\"default\", # Default: \"default\"\n timeout=300, # Default: 300s\n max_retries=3, # Default: 3\n compression=False # Default: False\n)\n\n# Execute query (returns raw tuples)\nresult = client.execute(\"SELECT now() AS current_time, version()\")\n\n# Get DataFrame (pandas required)\ndf = client.query_to_df(\"\"\"\n SELECT table, engine \n FROM system.tables \n WHERE database = currentDatabase()\n LIMIT 5\n\"\"\")\n```\n\n## Key Features\n- **HTTP Interface** - No native protocol dependency\n- **External Tables** - Pass data directly in queries\n- **Smart Batching** - Automatic chunking for large results\n- **Error Resilient** - Built-in retry mechanism\n- **Pandas Support** - Direct DataFrame conversion\n\n## Advanced Examples\n\n### External Tables\n```python\ndata = {\n 'users': [\n {'user_id': 1, 'name': 'Alice'},\n {'user_id': 2, 'name': 'Bob'}\n ]\n}\n\nexternal = [{\n 'name': 'ext_users',\n 'structure': [('user_id', 'UInt32'), ('name', 'String')],\n 'data': data['users']\n}]\n\ndf = client.query_to_df(\"\"\"\n SELECT u.name, count() as logins\n FROM ext_users u\n JOIN system.query_log q ON q.user = u.name\n GROUP BY u.name\n\"\"\", external_tables=external)\n```\n\n### Batch Processing\n```python\n# Processes in 100k row batches with auto-retry\nlarge_df = client.query_to_df(\n \"SELECT * FROM billion_row_table\",\n batch_size=100000, # Initial batch size\n memory_safe=True # Enables memory limits\n)\n```\n\n## Configuration Reference\n\n| Parameter | Type | Default | Description |\n|-----------------|------------|-------------|--------------------------------------|\n| `host` | str | - | Server hostname or IP |\n| `port` | int/str | 8123 | HTTP interface port |\n| `username` | str | \"default\" | Authentication username |\n| `password` | str | \"\" | Authentication password |\n| `database` | str | \"default\" | Default database context |\n| `timeout` | int | 300 | Query timeout in seconds |\n| `max_retries` | int | 3 | Connection retry attempts |\n| `compression` | bool | False | Enable gzip/deflate compression |\n| `verify_ssl` | bool | True | Verify SSL certificates |\n\n## License\nMIT License - See [LICENSE](LICENSE) for full text.\n\n> **Note**: Requires Python 3.7+ and `requests` package. Pandas needed for DataFrame support.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Lightweight HTTP client for ClickHouse",
"version": "0.1.6",
"project_urls": null,
"split_keywords": [
"clickhouse",
" http",
" driver",
" database"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c90e5e3d6534dcae9b7346793f78e1534843b5b51296e9a7fc69128dda104009",
"md5": "cd14383649b78b3e7adf6b7ccd492201",
"sha256": "1e9d112b3cb0487b87f26def0ae2891ec7a68d29498e63f9e07eca737509b236"
},
"downloads": -1,
"filename": "clickhouse_driver_http-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cd14383649b78b3e7adf6b7ccd492201",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6467,
"upload_time": "2025-07-31T15:46:17",
"upload_time_iso_8601": "2025-07-31T15:46:17.661825Z",
"url": "https://files.pythonhosted.org/packages/c9/0e/5e3d6534dcae9b7346793f78e1534843b5b51296e9a7fc69128dda104009/clickhouse_driver_http-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "209857c23523539e377714c898c0561b389c0baa024f8411d15cc47d980abe20",
"md5": "4eb33e3009f427e510a1d3085312a85e",
"sha256": "54b0a5883a4eddb75f2bd8e683680eefe828fa13298ac73a67b13c450a49c4ba"
},
"downloads": -1,
"filename": "clickhouse-driver-http-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "4eb33e3009f427e510a1d3085312a85e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6243,
"upload_time": "2025-07-31T15:46:18",
"upload_time_iso_8601": "2025-07-31T15:46:18.548577Z",
"url": "https://files.pythonhosted.org/packages/20/98/57c23523539e377714c898c0561b389c0baa024f8411d15cc47d980abe20/clickhouse-driver-http-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 15:46:18",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "clickhouse-driver-http"
}
JSON