Skip to main content
dbt 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.
Beta, not yet GA. The ClickHouse adapter for dbt OSS and dbt v2 is in Beta, and the dbt platform connection is in Private Beta. The dbt Core 1.x adapter, dbt-clickhouse, is GA and supported for production use; nothing on this page changes that.
The dbt Core 1.x documentation also applies to dbt OSS and dbt v2. The new 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 OSS, dbt v2 and the dbt platform. The exceptions are documented in the v1 vs v2 parity tables below.
dbt OSS is the open-source (Apache 2.0) build of the v2 engine. See terminology and availability for how it relates to dbt v2 and the dbt platform.
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.

Details on current status

Beta means that almost all v1 features work with documented limits. The features that are still pending are listed in v1 vs v2 parity and that list shrinks with every release. We recommend evaluating dbt v2 in development or staging first, and keeping production on dbt Core 1.x if your project depends on any of the pending features or you need the guarantees of a GA release. We measure the dbt v2 adapter against the dbt Core 1.x integration test suite of dbt-clickhouse. Today, the adapter passes ~98% of the v1 suite (270 of the 276 tests that apply to dbt v2). The remaining failures are engine-side differences, not ClickHouse ones: query comments, query_id in run results and the check for a hook configured under both pre-hook and pre_hook. See v1 vs v2 parity for the feature-by-feature picture. Next steps: query comments, query_id in run results, 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. We are working with dbt Labs on the timeline and will update this page when it’s ready.

Out of scope for Beta

Features exclusive to v2, such as the ClickHouse SQL intelligence (static analysis, LSP, column awareness), the Semantic Layer and additional dbt platform auth methods, are outside the Beta scope. Their status is covered in dbt v2 specific functionality.

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

Model configuration

Testing and docs

Cluster and Cloud

Macros and operations

Connectivity and auth

Not planned for v2

A few v1 options are deliberately not carried over to v2. They are listed here so the parity tables above only contain work that is planned.

dbt v2 specific functionality

dbt v2 adds capabilities that have no equivalent in dbt Core 1.x. They are outside the Beta scope and will come later: most of them build on the engine’s understanding of the SQL dialect, which does not exist for ClickHouse yet, but we are working on it. Same legend as above, plus In progress for work under way. Tracked in ClickHouse/dbt-clickhouse#736.