---
id: django-clickhouse-backend
version: "2.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# django-clickhouse-backend — Django clickHouse database backend

License: permissive · Maintenance: active · Downloads: 152.4K/mo

## What it is and what it does

Django ClickHouse Backend is a Django database backend that bridges Django's ORM to ClickHouse, a columnar analytics database. It lets you define ClickHouse tables using Django models and query them through the familiar ORM API, eliminating the need for intermediate storage or manual data synchronization. The backend uses clickhouse-driver for native TCP protocol connections and includes connection pooling.

The package supports most Django ORM operations, ClickHouse-specific features like table engines and skipping indexes, schema migrations, test database creation, and numpy/pandas result deserialization. However, it has important limitations: ClickHouse lacks transaction and constraint support, so foreign keys and unique constraints are not enforced at the database level; outer joins behave differently (missing columns become zero/empty rather than NULL); and aggregation functions return 0 or NaN instead of NULL on empty datasets. Multi-database routing is typically used to keep ClickHouse models separate from relational tables in the same Django project.

Use it for:

- Store and query high-volume event logs (network traffic, application metrics, security events) using Django models without building a separate pipeline.
- Build analytics dashboards that read from ClickHouse while keeping transactional data in PostgreSQL or MySQL via Django's multi-database router.
- Run time-series aggregations and sampling queries on large datasets using ClickHouse-specific clauses through Django ORM.
- Migrate an existing Django application to use ClickHouse for analytical tables without rewriting query code or losing ORM familiarity.
- Test ClickHouse table schemas and migrations in a Django TestCase or pytest-django environment before deploying to production.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Django database backend that lets you use Django ORM to query and manage ClickHouse tables directly, treating ClickHouse like any other Django-supported database.

Yes, if you need to integrate ClickHouse into a Django project and want to avoid writing raw SQL or managing a separate driver. The low install friction, active maintenance, and MIT license make it a practical choice. However, carefully evaluate the limitations: no transaction support, missing constraint enforcement, and non-standard NULL semantics in joins and aggregations. Test migrations thoroughly in a staging environment before production use, and confirm that your query patterns fit within the supported ORM subset.

## Install

pip install django-clickhouse-backend
uv add django-clickhouse-backend
poetry add django-clickhouse-backend

## Installing django-clickhouse-backend

Before you install: Low friction install with only two runtime dependencies (django and clickhouse-driver). Actively maintained with a recent release and steady repository activity.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

pip install django-clickhouse-backend

# In settings.py
INSTALLED_APPS = ["django_clickhouse_backend"]
DATABASES = {
    "clickhouse": {
        "ENGINE": "django_clickhouse_backend.backend",
        "HOST": "localhost",
        "NAME": "default"
    }
}

# In models.py
from django_clickhouse_backend import models
class Event(models.ClickhouseModel):
    timestamp = models.DateTime64Field()
    content = models.StringField()

Requires Django >= 3.2 and Python >= 3.7; ClickHouse server 22.x.y.z or later is suggested. No transaction support—migrations must be fully tested before production deployment.

Verify before relying:

- Extent of ORM feature parity with standard Django backends (which ORM operations are fully supported vs. partially or not supported)
- Performance characteristics and query optimization guidance for large event tables
- Compatibility matrix details for specific ClickHouse server versions beyond the 22.x.y.z suggestion

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 152.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

django clickhouse backend, django orm clickhouse, clickhouse database adapter, django clickhouse integration, clickhouse django driver, django multi-database routing, clickhouse table models, django-integration, columnar-analytics, multi-database-routing

[View on SkillFed](https://skillfed.io/packages/django-clickhouse-backend) · [View on PyPI](https://pypi.org/project/django-clickhouse-backend/)