Metadata-Version: 2.4
Name: chty
Version: 0.1.2
Summary: Type-safe ClickHouse query parameter codegen from SQL files
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: clickhouse-connect>=0.9.2
Requires-Dist: pandas>=2.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.4.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.0.0; extra == 'docs'
Description-Content-Type: text/markdown

# chty

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

[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://treygilliland.github.io/chty/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
# 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:

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

Generate typed Python code:

```bash
# 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:

```python
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:

```bash
# 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/](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](CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](LICENSE) for details.
