ClickHouse 不能直接作为 Django 默认数据库，因其不支持事务、外键、行级锁及标准 SQL 语义，与 Django ORM 架构冲突；硬配置会导致迁移失败、save 报错、Admin 异常。
ClickHouse 为什么不能直接当 Django 默认数据库用
Django 的 ORM 默认假设数据库支持事务、外键、行级锁和标准 SQL 语法，而 ClickHouse 是列式 OLAP 数据库，不支持事务、没有外键约束，INSERT 是追加写入，UPDATE/DELETE 需要 MUTATION（异步且低效），JOIN 性能差且语义不同于 PostgreSQL/MySQL。硬把 DATABASES['default'] 指向 ClickHouse 会导致 makemigrations 失败、Model.save() 报错、Admin 后台无法加载——这不是配置问题，是架构冲突。
- 别在
settings.py里把 ClickHouse 配置成default数据库 - 不要继承
models.Model并尝试用syncdb或migrate管理 ClickHouse 表结构 - 用原生 SQL 或专用客户端操作 ClickHouse，Django ORM 只负责业务逻辑和 Web 层
用 django-clickhouse 插件同步日志数据到 ClickHouse
django-clickhouse 是目前最轻量、适配 Django 3+/4+ 的同步方案，它不接管 ORM，而是提供一个 ClickHouseModel 基类 + 异步写入队列，适合日志类 append-only 场景。关键点在于：它只同步数据，不反向映射回 Django Model；表结构需手动建好或用 create_table 方法初始化。
- 安装：
pip install django-clickhouse，并在INSTALLED_APPS加'django_clickhouse' - 定义日志模型时继承
ClickHouseModel，字段类型对应 ClickHouse 类型（如DateTime64Field、StringField、UInt64Field） - 首次部署需显式调用
YourLogModel.create_table()，否则查不到表 - 写入用
YourLogModel.insert([dict(...), ...])，不是.save()；批量插入比单条快 10 倍以上
从 Django 视图中安全查询 ClickHouse 日志
不能用 objects.filter() 查 ClickHouseModel，它没 QuerySet 接口。必须用 clickhouse_driver 客户端直连，拼 SQL 查询。常见错误是把 Web 请求参数未经校验拼进 SQL，导致注入或语法错误；另一个坑是忘记加 WHERE event_time >= today - 7 这类时间分区过滤，全表扫描拖垮集群。
- 连接复用：在
settings.py配置CLICKHOUSE_HOST/PORT，用模块级全局Client实例，避免每次请求新建连接 - 参数化查询：用
client.execute("SELECT * FROM logs WHERE level = {level:String}", {"level": "ERROR"})，别用 f-string - 强制时间范围：所有日志查询默认加
AND event_time >= {start:DateTime64} AND event_time ，防止误操作扫全量 - 聚合结果转字典：用
client.execute(..., with_column_types=True)获取字段名，再 zip 成[dict(zip(columns, row)) for row in results]
日志写入性能瓶颈在哪？怎么绕过
真实场景下，高频日志（比如每秒上千条）直接走 HTTP 或原生客户端写 ClickHouse，容易因网络抖动、单连接吞吐不足、Python GIL 锁竞争导致堆积。ClickHouse 自身推荐的高吞吐写法是：用 INSERT INTO table FORMAT JSONEachRow 批量提交，配合 Nginx 缓存或 Kafka 中转。Django 层只需把日志推到队列，不关心落盘细节。
立即学习“Python免费学习笔记（深入）”；
- 别在视图或信号里同步调用
insert()；改用celery或redis queue异步推送 - 攒批：每 100 条或 500ms 触发一次批量
INSERT，比单条快 3–5 倍 - 字段精简：日志模型只保留分析必需字段（如
event_time,level,path,status_code,duration_ms），去掉user_agent这类长文本（可存 S3 后关联） - 分区策略：按天建表（
logs_20240501）或用ReplacingMergeTree+event_time分区，避免单表过大
ClickHouse 和 Django 是两套工具链，强行缝合只会放大各自的弱点。真正落地的关键，是明确边界：Django 负责接收、校验、分发日志；ClickHouse 负责存储、压缩、聚合；中间用队列或文件缓冲。任何试图让 Django “管理” ClickHouse 表结构或事务的方案，都会在数据量上来后暴露设计缺陷。
