---
id: clickhouse-sqlalchemy
version: "0.3.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# clickhouse-sqlalchemy — Simple ClickHouse SQLAlchemy Dialect

License: permissive · Maintenance: active · Downloads: 2.1M/mo

## What it is and what it does

ClickHouse SQLAlchemy is a SQLAlchemy dialect that bridges Python's SQLAlchemy ORM to ClickHouse, an open-source columnar database. It lets you define tables, insert data, and query ClickHouse using familiar SQLAlchemy patterns—Column definitions, declarative base classes, and session queries—rather than raw SQL or ClickHouse-specific clients. The dialect supports three transport mechanisms: native TCP (recommended), async TCP via asynch, and HTTP via requests, giving you flexibility in how your application connects to ClickHouse.

The package is in Beta status and has been actively maintained, with recent commits and a modest but stable user base. It supports Python 3.7 through 3.12 and declares no runtime dependencies, though you must separately install whichever transport library your application needs. This design keeps the package lightweight but places the burden of dependency management on you.

Use it for:

- Build a Python web application that stores analytics events in ClickHouse using SQLAlchemy ORM patterns instead of raw SQL.
- Query ClickHouse tables from a data science notebook using declarative table definitions and session queries.
- Integrate ClickHouse as a backend for a Python application that already uses SQLAlchemy for other databases.
- Set up async queries to ClickHouse in a high-concurrency service using the asynch transport.
- Migrate from another SQLAlchemy-supported database to ClickHouse with minimal ORM code changes.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

SQLAlchemy dialect for ClickHouse that enables ORM-style database access via native TCP, async TCP, or HTTP interfaces.

Yes, if you are already committed to SQLAlchemy and need ClickHouse support. The dialect is actively maintained, permissively licensed, and has no dependency bloat. However, you must manually install clickhouse-driver, asynch, or requests depending on your transport choice—verify this requirement before adding it to your project.

## Install

pip install clickhouse-sqlalchemy
uv add clickhouse-sqlalchemy
poetry add clickhouse-sqlalchemy

## Installing clickhouse-sqlalchemy

Before you install: High install friction: the package declares no runtime dependencies, but the description indicates it requires one of clickhouse-driver, asynch, or requests to function—you must install the appropriate transport layer separately.

License in practice: MIT license is permissive; you can use this package in commercial and proprietary projects with minimal restrictions, provided you include the license notice.

Quickstart:

pip install clickhouse-sqlalchemy
from sqlalchemy import create_engine
from clickhouse_sqlalchemy import make_session, get_declarative_base
uri = 'clickhouse+native://localhost/default'
engine = create_engine(uri)
session = make_session(engine)

You must separately install clickhouse-driver, asynch, or requests depending on your chosen transport (native, async native, or HTTP respectively).

Verify before relying:

- Whether clickhouse-driver, asynch, or requests are truly optional or whether at least one is required at runtime
- Current state of async support via asynch and whether it is production-ready
- Whether the package works with ClickHouse versions released after the latest release date

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: high
- Maintenance: active
- Downloads: 2.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

clickhouse sqlalchemy dialect, clickhouse orm python, sqlalchemy clickhouse driver, clickhouse database adapter, clickhouse python client, sqlalchemy-dialect, clickhouse-integration, analytics-db

[View on SkillFed](https://skillfed.io/packages/clickhouse-sqlalchemy) · [View on PyPI](https://pypi.org/project/clickhouse-sqlalchemy/)