chty

End-to-end type-safe ClickHouse query codegen from SQL files.

Installation

# Run directly without installation
uvx chty

# Or install globally
uv tool install chty

# Or use pip/pipx
pip install chty

Quick Start

Create a .sql file with ClickHouse parameterized queries:

-- queries/example.sql
SELECT number, number * {multiplier:Int32} AS result
FROM system.numbers
WHERE number < {limit:Int32}

Generate typed Python code:

# Local ClickHouse
chty generate queries/ --output generated/ --db-url clickhouse://user:pass@host:port

# ClickHouse Cloud
chty generate queries/ --output generated/ --db-url https://user:pass@host.clickhouse.cloud:8443

Use the generated code:

from generated.example import ExampleParams, ExampleQuery
import clickhouse_connect

client = clickhouse_connect.get_client(host="localhost")
params = ExampleParams(multiplier=3, limit=5)
query = ExampleQuery(client)

results = query.execute(params)
for row in results:
    print(f"Number: {row['number']}, Result: {row['result']}")

Validate generated code against your database schema:

# Detect schema drift in CI/CD or before deployment
chty validate generated/ --db-url clickhouse://user:pass@host:port

# Returns exit code 0 if valid, 1 if schema has changed

Features

• ✅ Type-safe parameters - Catch parameter errors at development time
• ✅ Type-safe results - Full autocomplete for result fields (with --db-url)
• ✅ Schema validation - Detect schema drift with chty validate
• ✅ Multiple execution methods - execute() and execute_df() for DataFrames
• ✅ Optional runtime validation - Validate result schema at runtime
• ✅ Zero runtime overhead - TypedDict is just type annotations

Why chty?

ClickHouse queries in Python lack type safety. chty connects your SQL queries directly to Python's type system:

Without chty:

• ❌ No autocomplete for query parameters or results
• ❌ Errors only caught at runtime
• ❌ No way to detect schema drift

With chty:

• ✅ Full type safety from SQL to Python
• ✅ IDE autocomplete everywhere
• ✅ Catch errors at development time
• ✅ Detect schema changes in CI/CD

Documentation

Full documentation is available at https://treygilliland.github.io/chty/

Development

Common development tasks are available via make. See Makefile for more.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

MIT License - see LICENSE for details.