Registry / data / dbt-clickhouse

dbt-clickhouse

JSON →
library1.10.0pypypiunverified

dbt-clickhouse is the ClickHouse plugin for dbt (data build tool), enabling data professionals to transform data in ClickHouse using SQL. It leverages dbt-core's capabilities, providing native support for ClickHouse-specific features like materialized views and database engines. Currently at version 1.10.0, the library maintains an active release cadence, frequently aligning with new dbt-core versions and introducing ClickHouse-specific enhancements.

pip install dbt-clickhouse
INSTALL
IMPORT
SIG · DBT-CLICKHOUSE
D
dbt-clickhouse
datapythonv1.10.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

This quickstart demonstrates how to configure and run a simple dbt project with dbt-clickhouse programmatically using Python. It creates the necessary `profiles.yml`, `dbt_project.yml`, and a sample model, then attempts to execute `dbt debug` and `dbt run`. Ensure you have a running ClickHouse instance accessible via the specified host and port (defaults to localhost:8123).

import os import shutil from dbt.cli.main import dbtRunner, dbtUsageException # Define paths for the quickstart project project_dir = "dbt_clickhouse_quickstart_project" profiles_dir = ".dbt" # Default location for profiles.yml # Clean up previous runs to ensure a fresh start if os.path.exists(project_dir): shutil.rmtree(project_dir) if os.path.exists(profiles_dir): shutil.rmtree(profiles_dir) # Create necessary directories os.makedirs(project_dir) os.makedirs(os.path.join(project_dir, "models")) os.makedirs(profiles_dir) # --- 1. Create profiles.yml for ClickHouse connection --- # Using environment variables for connection details, falling back to localhost defaults profiles_content = f""" dbt_clickhouse_quickstart: target: dev outputs: dev: type: clickhouse host: {os.environ.get('DBT_CLICKHOUSE_HOST', 'localhost')} port: {os.environ.get('DBT_CLICKHOUSE_PORT', '8123')} user: {os.environ.get('DBT_CLICKHOUSE_USER', 'default')} password: {os.environ.get('DBT_CLICKHOUSE_PASSWORD', '')} database: {os.environ.get('DBT_CLICKHOUSE_DATABASE', 'default')} schema: default # In ClickHouse, database acts as schema for dbt interface: http # or native secure: false verify: false """ with open(os.path.join(profiles_dir, 'profiles.yml'), 'w') as f: f.write(profiles_content) # --- 2. Create dbt_project.yml to link to the profile --- dbt_project_content = f""" name: 'dbt_clickhouse_quickstart' version: '1.0.0' config-version: 2 profile: 'dbt_clickhouse_quickstart' model-paths: ["models"] """ with open(os.path.join(project_dir, 'dbt_project.yml'), 'w') as f: f.write(dbt_project_content) # --- 3. Create a simple SQL model file --- model_content = """ {{ config(materialized='table') }} SELECT 1 as id, 'hello dbt clickhouse' as value """ with open(os.path.join(project_dir, 'models', 'my_test_model.sql'), 'w') as f: f.write(model_content) # --- 4. Run dbt commands programmatically --- dbt = dbtRunner() print("\n--- Running dbt debug to test connection ---") # The debug command does not require an active ClickHouse server to run, but will report connection errors debug_res = dbt.invoke(["debug", "--project-dir", project_dir, "--profiles-dir", profiles_dir]) if debug_res.success: print("dbt debug successful (connection details printed, may show connectivity errors if ClickHouse is not running).") else: print(f"dbt debug failed: {debug_res.exception}") print("\n--- Attempting to run dbt run (requires a running ClickHouse instance) ---") try: run_res = dbt.invoke(["run", "--project-dir", project_dir, "--profiles-dir", profiles_dir]) if run_res.success: print("dbt run successful. Model 'my_test_model' should be created as a table in ClickHouse.") else: print(f"dbt run failed: {run_res.exception}. Ensure ClickHouse is running and accessible.") except dbtUsageException as e: print(f"dbt CLI usage error: {e}") except Exception as e: print(f"An unexpected error occurred during dbt run: {e}") # Clean up the created files and directories shutil.rmtree(project_dir) shutil.rmtree(profiles_dir) print("\nCleaned up quickstart files.")
dbt --version
Debug
Known issues
gotchaIn v1.10.0, the `catchup: False` configuration flag for materialized views (`materialized='materialized_view'`) is now strictly respected during full refresh operations, preventing backfilling of historical data. Previously, this might have been ignored in some scenarios.
fix
Review your materialized view configurations. If you rely on historical data backfilling during full refreshes, ensure `catchup: True` is explicitly set or remove the `catchup` configuration if `True` is the default behavior you expect.
affects: 1.10.0+
breakingA regression in dbt-clickhouse v1.9.4 caused `dbt test` commands to fail with `macro 'dbt_macro__get_expected_sql' takes not more than 2 argument(s)` errors.
fix
Users on version 1.9.4 experiencing this issue must upgrade to dbt-clickhouse v1.9.5 or a later version to fix the `dbt test` functionality.
affects: 1.9.4
gotchadbt-clickhouse versions have specific compatibility requirements with dbt-core versions. For instance, v1.9.2 limited dbt-core to `<1.10.X`, while v1.9.7 added official support for dbt-core 1.10. Using incompatible versions can lead to unexpected errors or features not working.
fix
Always check the dbt-clickhouse release notes or official documentation for the compatible dbt-core version range when upgrading either library. Ensure your `dbt-clickhouse` and `dbt-core` versions are aligned (e.g., `pip install dbt-core==X.Y.Z dbt-clickhouse==A.B.C`).
affects: All versions
gotchadbt-clickhouse v1.9.8 updated its minimum requirement for `dbt-adapters` to `1.16.7` to resolve compatibility issues. Older versions of `dbt-adapters` might cause problems when used with `dbt-clickhouse 1.9.8` or newer.
fix
When installing or upgrading dbt-clickhouse 1.9.8 or later, ensure `dbt-adapters` is also updated to `1.16.7` or a more recent compatible version. `pip install dbt-clickhouse` typically handles this by installing the latest compatible dependencies.
affects: 1.9.8+
Errors
Common errors & fixes
Code: 62. DB::Exception: Syntax error: failed at position 312 ('empty') (line 15, col 9): empty
This error occurs when using an outdated version of ClickHouse that is incompatible with the dbt-clickhouse adapter.
fix
Upgrade ClickHouse to a version compatible with dbt-clickhouse, such as 22.7.1 or newer.
DB::Exception: Syntax error: failed at position 201 ('ON') (line 5, col 5): ON CLUSTER
This error arises due to a bug in dbt-clickhouse when using the 'ON CLUSTER' clause in a clustered ClickHouse environment.
fix
Upgrade dbt-clickhouse to version 1.4.8 or later to resolve the issue.
Code: 373. DB::Exception: Session is locked by a concurrent client. (SESSION_IS_LOCKED)
This error occurs when multiple dbt threads attempt to use the same ClickHouse session concurrently, leading to session locking.
fix
Ensure that each dbt thread uses a unique session by configuring the connection settings appropriately to avoid session reuse.
Connection refused
dbt cannot establish a connection to the ClickHouse server, often due to incorrect host, port, user, password, or security settings in profiles.yml, or the ClickHouse server not being accessible or running.
fix
Verify your profiles.yml configuration against your ClickHouse instance details, ensuring host, port, user, and password are correct. Confirm the ClickHouse server is running and accessible from where dbt is executed. Use `dbt debug` to test the connection.
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. dbt-clickhouse X.Y.Z requires dbt-core~=A.B.C, but you have dbt-core D.E.F which is incompatible.
This occurs when the installed dbt-clickhouse adapter version has a dependency on a specific range of dbt-core versions, and your currently installed dbt-core version falls outside that range.
fix
Install `dbt-core` and `dbt-clickhouse` together, explicitly specifying compatible versions. For dbt versions 1.8.0 and later, the recommended installation command is `python -m pip install dbt-core dbt-clickhouse`.
Upgrade
Version history
1.10.0latest on PyPI · released Feb 16, 2026
Audit
Dependencies
dbt-corerequiredPrimary dependency, dbt-clickhouse is an adapter for dbt-core.
dbt-adaptersrequiredShared adapter logic for dbt plugins. Minimum version 1.16.7 required by dbt-clickhouse v1.9.8+.
Agent activity
37 hits · last 30 days
node
32
OpenAI (training)
1
Resources
dbt-clickhouse — pip install dbt-clickhouse · libregistry