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
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.
fixUpgrade 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.
fixUpgrade 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.
fixEnsure 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.
fixVerify 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.
fixInstall `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+.