Set up docs MCPdbt is being rebuilt on a new engine, and ClickHouse is part of that from the start. ClickHouse now works with the new Rust-based dbt engine, in both dbt OSS and dbt v2, and for the first time you can connect to ClickHouse from the dbt platform. Your project does not change: the same models, tests and profiles that run on dbt Core 1.x today run on the new engine; only the binary is different.
ClickHouse is the first community adapter on dbt OSS, dbt v2 and the dbt platform. dbt’s own first-party adapters are launching alongside us; we are the first from outside dbt Labs. The dbt Core 1.x Python adapter, dbt-clickhouse, is not going away: we keep it current with dbt 1.x releases and maintain both adapters in parallel.
Live status is tracked in ClickHouse/dbt-clickhouse#660 (v2 parity with v1, one sub-issue per area) and ClickHouse/dbt-clickhouse#555 (dbt v2).
Try ClickHouse in the dbt platform
If you’re interested in testing the private beta, sign up through dbt Labs’ private beta form. The form belongs to dbt Labs, so the information you submit goes to dbt Labs, not to ClickHouse. Once enabled, follow Connect ClickHouse in the dbt documentation to set up the connection.
Terminology and availability
dbt is available in several forms, and the same adapter can run in more than one of them. This table explains each name and the current level of ClickHouse support.
| Term | What it is | ClickHouse status and how to get it |
|---|---|---|
| dbt Core 1.x | The Python-based dbt engine, open source (Apache 2.0). Our adapter is dbt-clickhouse, maintained in the ClickHouse GitHub organization and installed alongside dbt-core. |
GA, maintained. Keeps receiving releases in parallel with dbt v2. |
| dbt OSS | Full rewrite of the dbt engine in Rust, open source (Apache 2.0). This new version includes all v1 features plus several performance improvements. | Beta. Follow the dbt v2 upgrade guide and the ClickHouse setup page for v2 in the dbt documentation. The ClickHouse adapter ships inside the dbt binary; there is no separate package to install. |
| dbt v2 | dbt OSS plus additional features from dbt Labs: SQL comprehension, static analysis, LSP, a VS Code extension and column awareness. Closed source, licensed under the dbt Product Licensing Agreement. | Beta. The adapter runs with the v2 binary, but the new SQL features are not available for ClickHouse yet. |
| dbt platform | Hosted dbt, formerly dbt Cloud: Studio IDE, scheduled jobs, environments, Catalog, Semantic Layer. The platform runs dbt v2 only, so ClickHouse in the platform means the v2 adapter. | Private Beta. See how to request access. Setup: Connect ClickHouse in the dbt documentation. |
Beta status
We measure the dbt v2 adapter against the dbt Core 1.x integration test suite of dbt-clickhouse. Beta means that core dbt workflows and the ClickHouse Cloud feature set work with documented limits; full v1 parity and self-managed cluster support come after.
Today, the adapter passes more than 81% of the full v1 suite and 92% of the tests that apply to ClickHouse Cloud. Every materialization is at parity (view, table, incremental, materialized_view, dictionary, snapshot, seed, ephemeral), with the full set of table configs, model contracts, data and unit tests, docs persistence, clickhouse_s3source() and the dbt Core 1.x connection settings. The remaining failures relate to the self-managed cluster work listed below and a handful of engine-side differences. See v1 vs v2 parity for the feature-by-feature picture.
Next steps: ON CLUSTER DDL and the distributed materializations for self-managed clusters, grants, dbt clone, dbt source freshness from table metadata, fixes for the remaining bugs and passing the full v1 test suite to ensure full parity. The progress of all of these is tracked in ClickHouse/dbt-clickhouse#660, with one sub-issue per area.
GA is on the roadmap and will come soon. We’ll update the docs once it’s ready.
Out of scope for Beta
In addition to the v1 parity gaps listed below, a few features exclusive to v2 are outside the current scope but will come soon:
- Semantic Layer / MetricFlow. ClickHouse support has not been added yet. Tracked in dbt-labs/metricflow#2124.
- ClickHouse SQL intelligence in dbt v2 (dialect-aware validation, static analysis, LSP, column awareness in the VS Code extension). The adapter runs with the dbt v2 binary today but doesn’t include these features yet. Until then, static analysis is forced to
offfor ClickHouse projects and the engine writes no column-level lineage. Tracked in #736. - Additional auth methods beyond username and password in the dbt platform.
v1 vs v2 parity
The tables below compare the features available in dbt-clickhouse (v1) with their status in the dbt v2 adapter. Every feature listed is supported in v1 unless the notes say otherwise; the status column is for dbt v2 and applies equally to dbt OSS. The evolution of every pending item is tracked in ClickHouse/dbt-clickhouse#660.
Supported works today · Partial works with limits · Not yet pending implementation.
Materializations
| Feature | What it does | dbt v2 | Notes |
|---|---|---|---|
view |
Standard dbt view. | Supported | |
table |
Full rebuild with engine and DDL options. | Supported | |
incremental |
Append or merge new rows. | Supported | |
materialized_view |
ClickHouse MV that transforms at insert time. | Supported | |
dictionary |
ClickHouse dictionary for key lookups and joins. | Supported | |
snapshot |
Type 2 slowly changing dimensions. | Supported | |
seed |
Load CSVs as tables. | Supported | Numeric column types are inferred as Int64/Float64 instead of Int32/Float32; use column_types to set them explicitly. |
ephemeral |
Inline CTE, no object created. | Supported | |
distributed_table, distributed_incremental |
Sharded tables behind a Distributed engine. | Not yet |
Model configuration
| Feature | What it does | dbt v2 | Notes |
|---|---|---|---|
Engine, ORDER BY, PARTITION BY, PRIMARY KEY |
Core MergeTree DDL controls. | Supported | |
| TTL | Row and column expiration. | Supported | |
| Table and query settings | Per-model SETTINGS on DDL and on the insert. |
Supported | |
Projections, indexes, sql_header |
Secondary structures and prefix SQL. | Supported | |
| Model contracts and constraints | Column types and constraints enforced at build time. | Supported | |
| Schema evolution on incremental models | on_schema_change adds or syncs columns. |
Supported | |
Column codec and ttl |
Per-column compression and expiration. | Supported |
Testing and docs
| Feature | What it does | dbt v2 | Notes |
|---|---|---|---|
| Data tests | Generic and singular tests. | Supported | |
| Unit tests | Model logic against fixture inputs. | Supported | |
| Docs persistence | Descriptions written as ClickHouse comments. | Partial | Descriptions containing ; fail. |
| Catalog and docs generation | Column metadata for the docs site. | Supported | |
| Column-level lineage | Trace columns through the DAG. | Partial | New in v2 via the SQL compiler, not available in v1. dbt platform lineage renders only with identifier quoting disabled in dbt_project.yml; engine-side lineage needs the ClickHouse SQL dialect. |
Cluster and Cloud
| Feature | What it does | dbt v2 | Notes |
|---|---|---|---|
| ClickHouse Cloud | Recommended Beta setup. | Supported | |
| Multi-replica consistency | select_sequential_consistency and related read-after-write settings. |
Supported | |
ON CLUSTER and replicated engines |
DDL fan-out on self-managed clusters. | Not yet | Multi-node clusters in ClickHouse Cloud are supported. Other setups that require ON CLUSTER for DDL propagation are not supported yet. For self-managed deployments, test only against single-node clusters. |
EXCHANGE TABLES |
Atomic swap on rebuild. | Supported | |
| Custom connection settings | Profile-level custom_settings. |
Supported | |
| ClickHouse server version | Minimum server version. | Supported | 25.3+ on both engines. Reading UUID columns on v2 requires 26.7+ (older servers cannot convert UUID to Arrow). |
Macros and operations
| Feature | What it does | dbt v2 | Notes |
|---|---|---|---|
| S3 table function macro | clickhouse_s3source() reads S3 directly in a model. |
Supported | |
| Cross-database macros | Helpers such as those in dbt-utils. |
Supported | |
| Grants | GRANT statements from model config. |
Not yet | |
dbt clone |
Zero-copy CLONE AS between environments. |
Not yet | |
| Query ID in run results | query_id in adapter_response for system.query_log correlation. |
Not yet | |
query-comment |
Query comment configuration. | Not yet | query-comment: null is not honored yet. |
| Catalog integration (Iceberg) | Materialize into external catalogs. | Not yet | Not in v1 either; workarounds documented. |
Connectivity and auth
| Feature | What it does | dbt v2 | Notes |
|---|---|---|---|
| Protocol | How dbt talks to ClickHouse. | Supported | ADBC (Arrow over HTTP) on v2; HTTP and native on v1. |
| Username and password, TLS | Standard auth. | Supported | |
| mTLS client certificates | client_cert, client_cert_key, verify. |
Not yet | Driver work; the keys are accepted but ignored. |
| HTTP client options | connect_timeout, send_receive_timeout, sync_request_timeout, compress_block_size, server_host_name. |
Not yet | Accepted but ignored; server_host_name is unavailable. |