Environment:Helicone Helicone Python ClickHouse Migrations
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Database_Management |
| Last Updated | 2026-02-14 06:00 GMT |
Overview
Python 3.11+ environment with `tabulate` and `yarl` for running ClickHouse schema migrations via the `ch_hcone.py` CLI tool.
Description
This environment provides the Python runtime and dependencies needed to manage ClickHouse database schema migrations. The `ch_hcone.py` script is a CLI tool that reads SQL migration files from the `clickhouse/migrations/` directory, tracks applied migrations, and executes them against the ClickHouse server via its HTTP interface. It uses `tabulate` for formatted output and `yarl` for URL parsing/construction.
Usage
Use this environment when running ClickHouse schema migrations during local development setup or deployment. It is required by the `Ch_Hcone_Migrate` implementation and is invoked as part of the Docker Compose setup flow.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux (Ubuntu 20.04+) or macOS | Docker migration runner uses Python 3.12 slim |
| Python | 3.11+ | Production Docker uses 3.12-slim-bookworm |
| Network | HTTP access to ClickHouse on port 8123 | Default local: `http://localhost:18123` |
Dependencies
Python Packages
- `tabulate` >= 0.9.0 (formatted table output for migration status)
- `yarl` >= 1.15.2 (URL parsing for ClickHouse HTTP endpoint)
ClickHouse Server
- ClickHouse Server 24.3+ (target database)
- HTTP interface enabled on port 8123
Credentials
The following environment variables or CLI arguments are required:
- `CLICKHOUSE_HOST`: ClickHouse HTTP endpoint (e.g., `http://localhost:18123`)
- `CLICKHOUSE_USER`: ClickHouse username (default: `default`)
- `CLICKHOUSE_PASSWORD`: ClickHouse password (default: empty for local)
Quick Install
# Install Python dependencies
cd clickhouse && pip install -r requirements.txt
# Run migrations (local development)
python ch_hcone.py --host http://localhost:18123 --user default migrate
# Check migration status
python ch_hcone.py --host http://localhost:18123 --user default status
Code Evidence
Python dependencies from `clickhouse/requirements.txt:1-2`:
tabulate>=0.9.0
yarl>=1.15.2
Docker migration runner from `docker/dockerfiles/dockerfile_migrations`:
FROM python:3.12-slim-bookworm
Migration CLI entry point from `clickhouse/ch_hcone.py:258-350`:
# CLI tool for ClickHouse schema management
# Reads SQL files from migrations/ directory
# Tracks applied migrations in a metadata table
# Supports: migrate, status, rollback commands
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `ModuleNotFoundError: No module named 'tabulate'` | Python dependencies not installed | Run `pip install -r clickhouse/requirements.txt` |
| `Connection refused` on port 8123 | ClickHouse not running | Start ClickHouse via Docker Compose: `docker compose up clickhouse` |
| `Code: 60. DB::Exception: Table already exists` | Migration partially applied | Check migration status and manually resolve; re-run with caution |
Compatibility Notes
- Docker vs Local: The Docker migration runner uses Python 3.12-slim-bookworm, while local development may use any Python 3.11+. Ensure compatible versions.
- Alternative Runner: A shell-based migration runner (`ch_local_hcone.sh`) also exists for environments without Python, using the `clickhouse-client` CLI directly.