dbt Core v2, Fusion and Platform

dbt is being rebuilt on a new engine, and ClickHouse is part of that from the start. You can now run dbt against ClickHouse on the new Rust engine (dbt Core v2 and dbt Fusion), and for the first time you can connect to ClickHouse from the dbt platform with the v2 connector. 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 v2 and in 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.

Not production-ready. The dbt Core v2 engine, its ClickHouse adapter and the dbt platform connection are not yet generally available (GA). Use them only in development or staging projects.

The dbt Core 1.x documentation also applies to dbt Core v2. The adapter behaves the same way on both engines: the profiles, model configs, materializations and macros described in the other dbt pages work unchanged on dbt Core v2, dbt Fusion and the dbt platform. The exceptions are documented in the v1 vs v2 parity table below.

Live status is tracked in ClickHouse/dbt-clickhouse#660 (dbt Core v2 parity, one sub-issue per area) and ClickHouse/dbt-clickhouse#555 (dbt Fusion).

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 v2.
dbt Core v2	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 Fusion	dbt v2 plus additional features from dbt Labs: SQL comprehension, static analysis, LSP, a VS Code extension and column awareness. Dialect-specific SQL intelligence is built per database. Closed source, licensed under the dbt Product Licensing Agreement.	Beta. The adapter runs with the Fusion 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 dbt Core v2 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 Fusion (dialect-aware validation, static analysis, LSP, column awareness in the VS Code extension). The adapter runs with the Fusion binary today but doesn’t include these features yet. Until then, static analysis is forced to off for 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 Core v2 adapter. Every feature listed is supported in v1 unless the notes say otherwise; the status column is for dbt Core v2. 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 Core 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 Core v2
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 Core 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 Core 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 Core 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 Core 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.

Data sources

Data visualization

Data ingestion

Data integrations

SQL-clients

Tools

Try ClickHouse in the dbt platform

Terminology and availability

Beta status

Out of scope for Beta

v1 vs v2 parity

Materializations

Model configuration

Testing and docs

Cluster and Cloud

Macros and operations

Connectivity and auth

​Try ClickHouse in the dbt platform

​Terminology and availability

​Beta status

​Out of scope for Beta

​v1 vs v2 parity

​Materializations

​Model configuration

​Testing and docs

​Cluster and Cloud

​Macros and operations

​Connectivity and auth

Try ClickHouse in the dbt platform

Terminology and availability

Beta status

Out of scope for Beta

v1 vs v2 parity

Materializations

Model configuration

Testing and docs

Cluster and Cloud

Macros and operations

Connectivity and auth