Registry /
database / django-clickhouse-backend
Install & Compatibility
Where this runs
tested against v1.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.018s · 73.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.9s · import 0.016s · 74MB
73MB installed
● package 73MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
clickhouse_backend
✓ import clickhouse_backend
✗ from clickhouse_backend import ...
The backend is a package, not a module. Import the package and configure DATABASES engine as 'clickhouse_backend.backend'
DatabaseOperations
✓ from clickhouse_backend.operations import DatabaseOperations
✗ from clickhouse_backend import DatabaseOperations
DatabaseOperations is in the operations submodule
Configure Django to use ClickHouse backend and test the connection.
import os
# Configure Django settings
DATABASES = {
'default': {
'ENGINE': 'clickhouse_backend.backend',
'NAME': 'default',
'USER': os.environ.get('CLICKHOUSE_USER', 'default'),
'PASSWORD': os.environ.get('CLICKHOUSE_PASSWORD', ''),
'HOST': os.environ.get('CLICKHOUSE_HOST', 'localhost'),
'PORT': os.environ.get('CLICKHOUSE_PORT', '8123'),
'OPTIONS': {
'settings': {
'mutations_sync': 2,
},
},
}
}
# Verify connection
from django.db import connection
with connection.cursor() as cursor:
cursor.execute('SELECT version()')
print(cursor.fetchone())
Debug
Known issues
breakingDjango 5.2 and above require django-clickhouse-backend >= 1.4.0. Using older versions with Django 5.2 will cause import errors.fixUpgrade to django-clickhouse-backend >= 1.4.0
affects: django-clickhouse-backend < 1.4.0 with Django >= 5.2
gotchaBulk_create uses db_default and default expressions incorrectly in v1.6.0. The default value object may appear in SQL instead of being resolved. This only affects bulk_create with db_default set.fixAvoid using db_default with bulk_create, or patch the DatabaseOperations class to handle default resolution. Fixed in future releases.
affects: 1.6.0
deprecatedindex_together is deprecated in Django 5.1 and removed in 5.2. Use Meta.indexes instead.fixReplace index_together with Meta.indexes and upgrade django-clickhouse-backend to >= 1.3.1
affects: Django >= 5.1 with django-clickhouse-backend < 1.3.1
Errors
Common errors & fixes
django.core.exceptions.ImproperlyConfigured: 'clickhouse_backend.backend' isn't an available database backend.
The clickhouse_backend package is not installed or not in PYTHONPATH.
fixRun: pip install django-clickhouse-backend
AttributeError: 'ReplicatedReplacingMergeTree' object has no attribute 'expressions'
Using a ReplicatedReplacingMergeTree with a version column (ver) in older versions (<1.1.7). The engine's expressions attribute is missing.
fixUpgrade to django-clickhouse-backend >= 1.1.7
Upgrade
Version history
1.6latest on PyPI · released Jan 12, 2026
Audit
Dependencies
No dependency data recorded yet.