chdb-sqlalchemy
SQLAlchemy dialect for chDB — the in-process OLAP SQL engine powered by ClickHouse.
chdb-sqlalchemy lets you use chDB as a SQLAlchemy backend, which in turn unlocks every Python data stack that already speaks SQLAlchemy: Django ORM, Flask-SQLAlchemy, pandas.read_sql(), Apache Superset, LangChain's SQLDatabaseToolkit, CrewAI's NL2SQLTool, and more.
v0.2.0 is live on PyPI — https://pypi.org/project/chdb-sqlalchemy/
What this is
chDB already supports DB-API 2.0 through chdb.dbapi. chdb-sqlalchemy adds the layer above that: a dialect that handles connection URIs, table reflection, type mapping, and the introspection contract SQLAlchemy expects.
The dialect is a thin wrapper — chDB's SQL surface is ClickHouse SQL, so most of the dialect's job is type mapping and reflection, not query rewriting.
Install
pip install chdb-sqlalchemy
Usage
Basic connection
from sqlalchemy import create_engine, text
# In-memory
engine = create_engine("chdb:///:memory:")
# Persistent
engine = create_engine("chdb:////tmp/my_chdb")
with engine.connect() as conn:
result = conn.execute(text("SELECT version()"))
print(result.scalar())
With pandas
import pandas as pd
from sqlalchemy import create_engine
engine = create_engine("chdb:////tmp/my_chdb")
df = pd.read_sql("SELECT * FROM file('data.parquet') LIMIT 100", engine)
With LangChain SQLDatabaseToolkit
from langchain_community.utilities import SQLDatabase
from langchain_community.agent_toolkits import SQLDatabaseToolkit
db = SQLDatabase.from_uri("chdb:////tmp/my_chdb")
toolkit = SQLDatabaseToolkit(db=db, llm=llm)
With CrewAI NL2SQLTool
from crewai_tools import NL2SQLTool
nl2sql = NL2SQLTool(db_uri="chdb:////tmp/my_chdb")
URI format
chdb:///:memory: # in-memory session
chdb:////absolute/path/to/dir # persistent session at that directory
chdb:///./relative/path # persistent session at a relative path
There are no host, port, username, or password components — chDB runs in-process. Authentication is delegated to the surrounding application.
Type mapping
| ClickHouse type | SQLAlchemy type |
|---|---|
String, FixedString |
String |
UInt8 … UInt64, Int8 … Int64 |
Integer, BigInteger |
Float32, Float64 |
Float |
Decimal(P, S) |
Numeric |
Date, Date32 |
Date |
DateTime, DateTime64 |
DateTime |
UUID |
Uuid |
Array(T) |
ARRAY |
Tuple(...), Map(K, V) |
JSON |
JSON (native) |
JSON |
Introspection support
Following the LangChain SQLDatabaseToolkit introspection contract, the dialect implements:
get_table_names()— list user tables visible to the session.get_columns()— name, type, nullability, default for each column.get_pk_constraint()— primary key columns (when aMergeTreeORDER BY is the de facto PK).get_foreign_keys()— empty list; chDB does not enforce foreign keys.get_indexes()— primary and secondary indexes fromsystem.data_skipping_indices.
Roadmap
- v0.1 — dialect registration, connection URI, basic type mapping, table reflection for
SQLDatabase.from_uri()andpandas.read_sql(). - v0.2 — full LangChain
SQLDatabaseToolkitand CrewAINL2SQLToolcertification — both rely on introspection that the v0.1 surface does not yet cover. - v0.3 —
remoteSecure()federated table support exposed as SQLAlchemyTableobjects.
Milestones land incrementally; check back here or follow @chdb_io for releases.
License
Apache 2.0 — see LICENSE.
Related
- Main chDB repository: https://github.com/chdb-io/chdb
- chDB documentation: https://clickhouse.com/docs/chdb
- chDB DB-API 2.0 module:
chdb.dbapiin the main repository. - LLM-friendly index: https://clickhouse.com/docs/chdb/llms.txt
- LangChain integration: https://github.com/chdb-io/langchain-chdb
- Community: https://discord.gg/D2Daa2fM5K
Metadata
Release files for chdb-sqlalchemy 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| chdb_sqlalchemy-0.2.1.tar.gz | 113.1 kB | Without provenance | Details for chdb_sqlalchemy-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| chdb_sqlalchemy-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for chdb_sqlalchemy-0.2.1-py3-none-any.whl |
Total release size: 173.2 kB
Release files / chdb_sqlalchemy-0.2.1.tar.gz
| Download URL | chdb_sqlalchemy-0.2.1.tar.gz |
|---|---|
| Size | 113.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
330a0c82b6ea958f6ea32a7f49b9f652215f1eb0275685252e55362eff812051
|
|
BLAKE2b-256 checksum How to use checksums |
faea4edb6cd72ac61aeccc51059480f348675f2732e98a5ec7dbd876cb96cca1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / chdb_sqlalchemy-0.2.1-py3-none-any.whl
| Download URL | chdb_sqlalchemy-0.2.1-py3-none-any.whl |
|---|---|
| Size | 60.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
62c666dbb1425e4ef88904fc655e5bda89d2b39a20e259cc97a926e683f26f8f
|
|
BLAKE2b-256 checksum How to use checksums |
ce69d94cb5de3c9682d2b47c630d5b6f78c0377350327ba357ddcf645cdc55b8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for chdb-sqlalchemy 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.