Implementation:Helicone Helicone Ch Hcone Migrate

Knowledge Sources	Helicone
Domains	Local Development, ClickHouse
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete tool for managing ClickHouse schema migrations via a Python CLI, provided by the clickhouse/ch_hcone.py module.

Description

ch_hcone.py is a 522-line Python CLI tool that manages ClickHouse database schema migrations. It reads SQL migration files from clickhouse/migrations/, tracks applied migrations in a helicone_migrations ClickHouse table, and executes pending migrations via HTTP requests to the ClickHouse server. The tool splits multi-statement SQL files into individual statements and executes them sequentially.

The core function run_migrations(args, retries=2, user=None, password=None) (lines 258-350) handles the migration workflow: loading applied migrations, previewing pending changes, prompting for confirmation, executing each migration file, and recording successful applications.

The main() function (lines 384-522) parses CLI arguments and dispatches to operations including --upgrade (apply all pending migrations), --start (start a standalone ClickHouse container and migrate), --list-migrations (show applied migrations), and --seed-roles (apply role/permission seeds).

Usage

Use after ClickHouse is running (either via Docker Compose or standalone). For local development with the Docker Compose stack, ClickHouse is available at http://localhost:18123.

Code Reference

Source Location

Repository: Helicone
File: clickhouse/ch_hcone.py (lines 258-350 for run_migrations, lines 384-522 for main)

Signature

def run_migrations(args, retries=2, user=None, password=None):
    """Apply all pending ClickHouse schema migrations."""

def main():
    """CLI entry point: parse arguments and dispatch to migration operations."""

Import

# Set up Python virtual environment and install dependencies
python3 -m venv venv
source venv/bin/activate
python3 -m pip install tabulate yarl

I/O Contract

Inputs

Name	Type	Required	Description
--upgrade	flag	Yes (for migration)	Triggers application of all pending migrations
--host	string	No	ClickHouse server hostname (default: `localhost`, or `CLICKHOUSE_HOST` env var)
--port	string	No	ClickHouse HTTP port (default: `18123`, or `CLICKHOUSE_PORT` env var)
--url	string	No	Full ClickHouse URL (overrides host/port, e.g. `http://localhost:18123`)
--user	string	No	ClickHouse user (default: `default`, or `CLICKHOUSE_USER` env var)
--password	string	No	ClickHouse password (prompted interactively if not provided and --no-password is not set)
--no-password	flag	No	Skip password prompt (use for local development with no password)
--skip-confirmation	flag	No	Skip interactive confirmation prompts before applying migrations
--list-migrations	flag	No	List all previously applied migrations in a table
--seed-roles	flag	No	Run seed files from `clickhouse/seeds/` after migrations
--test	flag	No	Run in test mode (uses alternate container name and port 19001)

Outputs

Name	Type	Description
Applied migrations	stdout	Progress log showing each migration applied with success/failure status
helicone_migrations table	ClickHouse table	Records of all applied migrations with timestamps
Schema changes	ClickHouse DDL	Tables, views, and other schema objects created by migration SQL files
Exit code	integer	0 on success, 1 on connection or migration failure

Usage Examples

Basic Usage

# Apply all pending migrations to local ClickHouse (no password)
python3 clickhouse/ch_hcone.py --upgrade --skip-confirmation --no-password

With Custom Host and Port

# Apply migrations to a specific ClickHouse instance
python3 clickhouse/ch_hcone.py --upgrade --skip-confirmation \
  --host clickhouse-server --port 8123 --user default --no-password

Using URL Directly

# Apply migrations using a full URL
python3 clickhouse/ch_hcone.py --upgrade --skip-confirmation \
  --url http://localhost:18123 --no-password

List Applied Migrations

# View all applied migrations in a formatted table
python3 clickhouse/ch_hcone.py --list-migrations --no-password

Start Standalone ClickHouse and Migrate

# Start a standalone ClickHouse container and apply all migrations
python3 clickhouse/ch_hcone.py --start --no-password

Seed Roles After Migration

# Apply migrations and then seed roles
python3 clickhouse/ch_hcone.py --upgrade --seed-roles --skip-confirmation --no-password

Related Pages

Implements Principle

Principle:Helicone_Helicone_Database_Migrations

Requires Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment