django-clickhouse-backend

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 on this page — 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

django-clickhouse-backend on PyPI

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

Evidence: django_clickhouse_backend-2.0-py3-none-any.whl

Keywords: Django, ClickHouse, database, backend, engine, driver

Tags

More Front-Ends packages