> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Status of the ClickHouse adapter in dbt OSS, dbt v2 and the dbt platform
# dbt OSS, v2 and Platform (Beta)
export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
if (link) {
return
Beta
;
}
return
Beta feature
;
};
export const ClickHouseSupportedBadge = () => {
return ;
};
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.
**Not production-ready.** The ClickHouse adapter for dbt OSS and dbt v2, 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 OSS and dbt 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 OSS, dbt v2 and the dbt platform. The exceptions are documented in the [v1 vs v2 parity](#parity) table below.
**dbt OSS** is the open-source (Apache 2.0) build of the v2 engine. See [terminology and availability](#terminology) for how it relates to dbt v2 and the dbt platform.
Live status is tracked in [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660) (v2 parity with v1, one sub-issue per area) and [ClickHouse/dbt-clickhouse#555](https://github.com/ClickHouse/dbt-clickhouse/issues/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](https://docs.google.com/forms/d/e/1FAIpQLScjHwRchnKarq_RpNM7hATjphNFxqBEePmAwRtSpMWG1snGHA/viewform). The form belongs to dbt Labs, so the information you submit goes to dbt Labs, not to ClickHouse. Once enabled, follow [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/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](https://github.com/ClickHouse/dbt-clickhouse) 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](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v2) and the [ClickHouse setup page for v2](https://docs.getdbt.com/docs/local/connect-data-platform/clickhouse-setup?version=2) 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](https://www.getdbt.com/dbt-fusion-engine-license-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](#request-access). Setup: [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/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](#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](https://github.com/ClickHouse/dbt-clickhouse/issues/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](https://github.com/dbt-labs/metricflow/pull/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 `off` for ClickHouse projects and the engine writes no column-level lineage. Tracked in [#736](https://github.com/ClickHouse/dbt-clickhouse/issues/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](https://github.com/ClickHouse/dbt-clickhouse/issues/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. |