dbt-clickhouse

dbt-clickhouse is the ClickHouse-maintained dbt adapter that ports dbt Core functionality to ClickHouse, the open-source column-oriented OLAP database. It lets analytics engineers define, materialize, and test models directly against ClickHouse using dbt’s standard project structure.

The adapter maps dbt materializations onto ClickHouse-native features: table, view, incremental, and materialized-view materializations, distributed tables for clustered deployments, and ClickHouse-specific column configurations such as codecs, TTLs, indexes, and projections.

What You Get

• A dbt adapter that targets ClickHouse as the transformation and query engine.
• Table, view, incremental, ephemeral, and materialized-view materializations.
• Distributed table and distributed incremental materializations for clustered ClickHouse.
• ClickHouse-specific configuration for codecs, TTLs, indexes, and projections.

Common Use Cases

• Modeling analytics data in ClickHouse using dbt’s standard project workflow.
• Building incremental and microbatch pipelines on high-volume event data.
• Managing distributed tables across a ClickHouse cluster through dbt.

Under The Hood

Architecture

The adapter lives under dbt/adapters/clickhouse and implements dbt’s adapter protocol: a connection manager wrapping the ClickHouse client, relation and column classes encoding ClickHouse types, and macro overrides (in dbt/include/clickhouse) that generate ClickHouse DDL/DML for each materialization. dbt Core discovers it through the adapter plugin entry point at runtime.

Tech Stack

Python built on dbt-core (>=1.9) and dbt-adapters, connecting through both clickhouse-connect (HTTP) and clickhouse-driver (native protocol). Testing and tooling use pytest, mypy, and a Makefile-driven workflow.

Code Quality

The repo has dedicated tests/unit and tests/integration suites with a conftest.py harness, mypy configuration, an explicit AI_POLICY.md, and CHANGELOG discipline. As an officially ClickHouse-maintained project it tracks dbt-core releases closely and documents supported features explicitly in the README.

API Design

Usage matches the standard dbt experience: install alongside dbt-core, define a ClickHouse target in profiles.yml, and set ClickHouse specifics through model config. Because it reuses dbt’s materialization vocabulary, existing dbt users adopt it with minimal friction, while ClickHouse power features remain reachable through config keys.