Django ClickHouse Backend

1.6.0 verified Mon Apr 27 auth: no python

A Django database backend for ClickHouse, providing ORM integration, migrations, and support for ClickHouse-specific features like MergeTree engines, distributed tables, and materialized views. Current version 1.6.0, released April 2025. Active development with quarterly releases.

pip install django-clickhouse-backend

Common errors

error django.core.exceptions.ImproperlyConfigured: 'clickhouse_backend.backend' isn't an available database backend. ↓

cause The clickhouse_backend package is not installed or not in PYTHONPATH.

fix

Run: pip install django-clickhouse-backend

error AttributeError: 'ReplicatedReplacingMergeTree' object has no attribute 'expressions' ↓

cause Using a ReplicatedReplacingMergeTree with a version column (ver) in older versions (<1.1.7). The engine's expressions attribute is missing.

fix

Upgrade to django-clickhouse-backend >= 1.1.7

Warnings

breaking Django 5.2 and above require django-clickhouse-backend >= 1.4.0. Using older versions with Django 5.2 will cause import errors. ↓

fix Upgrade to django-clickhouse-backend >= 1.4.0

gotcha Bulk_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. ↓

fix Avoid using db_default with bulk_create, or patch the DatabaseOperations class to handle default resolution. Fixed in future releases.

deprecated index_together is deprecated in Django 5.1 and removed in 5.2. Use Meta.indexes instead. ↓

fix Replace index_together with Meta.indexes and upgrade django-clickhouse-backend to >= 1.3.1

Imports

clickhouse_backend
wrong
```
from clickhouse_backend import ...
```
correct
```
import clickhouse_backend
```
The backend is a package, not a module. Import the package and configure DATABASES engine as 'clickhouse_backend.backend'

DatabaseOperations

wrong

from clickhouse_backend import DatabaseOperations

correct

from clickhouse_backend.operations import DatabaseOperations

DatabaseOperations is in the operations submodule

Quickstart

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())