Django本身不自动做读写分离,必须通过DATABASES配置主从库、自定义DatabaseRouter实现db_for_read/db_for_write/allow_relation/allow_migrate四个方法,并在DATABASE_ROUTERS中注册,缺一不可;漏掉allow_migrate或返回错误值会导致迁移失败。

直接上结论:Django 本身不自动做读写分离,必须靠 DATABASES 配置 + 自定义 DatabaseRouter 类 + DATABASE_ROUTERS 注册三者配合,缺一不可;漏掉 allow_migrate 控制或写错返回值,迁移会失败。
settings.py 中 DATABASES 配置的坑点
别名必须唯一且显式声明,“default”不能删,哪怕你从不手动用它——Django 的 manage.py migrate、shell 等命令默认都走这个别名。常见错误包括:
- 把主库和从库都配成
'default',结果只有最后一个生效 - 在数据库配置里加了
'OPTIONS': {'read_only': True}这类字段,Django 完全忽略——它不校验也不使用这些键 - HOST、PORT、NAME 等关键参数留空或写错类型(比如 PORT 写成字符串
"3306"而非整数3306),连接时静默 fallback 到localhost:3306 - 主从库用不同 MySQL 用户,从库用户必须有
SELECT权限,但不能有INSERT/UPDATE/DELETE——否则路由失效后写操作可能意外成功
db_for_read 和 db_for_write 必须成对实现
只写 db_for_read 不写 db_for_write,或反过来,会导致部分操作走默认库(default),读压力回流到主库。典型实现要满足:
-
db_for_read返回从库别名(如'replica'),但注意:它对所有模型生效,除非你按model.__name__或hints.get('instance')做条件判断 -
db_for_write几乎总是返回'default',因为写必须集中到主库;但如果用了分库策略(比如日志写'log_db'),这里也要对应返回 - 两个方法里禁止做 I/O 操作(比如查 Redis、发 HTTP 请求),否则每个 DB 查询都会被拖慢
- 事务内(
transaction.atomic())所有操作强制走同一库,此时db_for_read返回值会被忽略——这是设计使然,不是 bug
.using() 手动指定数据库的局限性
写 MyModel.objects.using('replica').all() 看似简单,但关联查询极易漏控:
安装、修复、更新或打包一个基于 Python 和 PyMySQL 实现的 Windows `mysql` 命令。适用于用户希望在 PowerShell/CMD 中输入 `mysql` 时重定向到 Python 实现、需要交互式输入 MySQL 连接信息、需要同步到当前用户本地 bin 目录,或需要将该能力封装成可公开复用的 Codex skill。
-
Book.objects.using('replica').select_related('author')中,Book查从库,author关联查询仍走default -
prefetch_related同理,外键或多对多的 prefetch 查询不会继承.using()设置 - Admin 后台默认全部走
default,必须重写get_queryset(self)并显式调.using('replica') - 如果模型用了
save(using='replica'),Django 会跳过路由,直接连从库——但 MySQL 从库通常拒绝写,立刻报错ERROR 1290 (HY000): The MySQL server is running with the --read-only option
验证读请求是否真走从库
别信日志,也别只看代码有没有写 .using()——最可靠的方法是抓包或查数据库连接来源:
- 临时登录从库执行
SHOW PROCESSLIST;,触发一次页面请求,看是否有来自应用服务器的新连接(User 字段应为从库配置的只读账号) - 在路由类的
db_for_read方法开头加print(f"READ → replica"),配合请求观察 stdout 输出(注意生产环境关掉) - 用
connections['replica'].cursor().execute("SELECT CONNECTION_ID()")在 view 中主动查当前连接 ID,再和SHOW PROCESSLIST对比 - 如果用了连接池(如
pymysql+DBUtils),需确认池子没复用主库连接——某些旧版驱动会在首次连接后缓存连接参数,导致后续.using('replica')实际仍连主库
真正容易被忽略的是:Django 的路由机制只控制 QuerySet 构建阶段的数据库选择,不控制底层连接复用逻辑;一旦连接建立,后续同一线程的查询只要没显式 .using(),就继续复用该连接——所以 db_for_read 的返回值必须稳定,不能依赖运行时状态(比如根据请求头动态选库),否则连接池行为会不可预测。










