The `clickhouse-sqlalchemy` library provides a SQLAlchemy dialect for connecting to and interacting with ClickHouse databases. It enables users to leverage SQLAlchemy's ORM and SQL Expression Language for querying and manipulating data in ClickHouse. The current version is `0.3.2`. The project releases updates on an as-needed basis rather than a fixed schedule.
pip install clickhouse-sqlalchemyVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to establish a connection to a ClickHouse database using SQLAlchemy's `create_engine` and execute basic SQL queries, including DDL and DML operations. It uses environment variables for connection details for secure and flexible configuration. A running ClickHouse instance is required.
Replace `ClickHouseEngine(...)` with `create_engine('clickhouse://...')` and `create_session(...)` with `sqlalchemy.orm.sessionmaker(bind=engine)()`.If nullable strings are desired, explicitly define columns using `sa.Column('name', sa.String(255), nullable=True)` or import `NullableString` from `clickhouse_sqlalchemy.types`.Use specific types like `DateTime(timezone=...)` or `DateTime64(precision=..., timezone=...)` from `clickhouse_sqlalchemy.types` for precise control over timestamp columns.
For complex types and features, it's often more robust to use `engine.execute(text('RAW SQL HERE'))` to run native ClickHouse queries directly, bypassing the ORM layer.Ensure `clickhouse-sqlalchemy` is correctly installed. If packaging, ensure the dialect is included. Sometimes, explicitly importing `clickhouse_sqlalchemy` or registering the dialect can help: `from clickhouse_sqlalchemy import dialect` (though usually not necessary with a proper install).
Downgrade the `infi.clickhouse_orm` package to version `1.0.4` or earlier. Add `infi.clickhouse_orm==1.0.4` to your `requirements.txt` and reinstall.
Adjust your `requirements.txt` or `pip install` commands to use a SQLAlchemy version compatible with `clickhouse-sqlalchemy==0.3.2`. For example, use `sqlalchemy==2.0.x` (where `x` is a compatible patch version).
This was a bug in earlier versions of `clickhouse-sqlalchemy` related to column compilation and `Nullable` types. Update `clickhouse-sqlalchemy` to a version where this fix has been merged (e.g., 0.1.6 or newer, or the latest 0.3.2).
While `session.execute(table.insert(), data)` often works correctly, when using ORM-style `session.add()`, ensure that `Nullable(String)` columns are either explicitly set to `None` or an empty string (`''`) if `None` is not handled gracefully by the driver in that context. This issue was reported in earlier versions and might be resolved by updating the library.
No dependency data recorded yet.