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 on it.

Install

django-clickhouse-backend on PyPI

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.

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.

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

Package facts

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

Tags

More Front-Ends packages

See also clickhouse-connect · infi.clickhouse-orm · django-clickhouse · clickhouse-pool · clickhouse-migrations · clickhouse-driver · clickhouse-sqlalchemy · django-snowflake · logtail-python · django-tasks-db