Django多数据库配置与读写分离教程

本文深入解析了Django多数据库配置与读写分离的核心实践，重点揭示了DatabaseRouter类必须完整实现db_for_read、db_for_write、allow_relation和allow_migrate四个方法的硬性要求——遗漏任一方法将直接引发AttributeError，而allow_relation和allow_migrate恰恰是实际项目中最常被忽略、却导致跨库关联失败或迁移异常的关键环节；文章不仅给出了可直接落地的PrimaryReplicaRouter范例，还系统梳理了配置陷阱（如DATABASE_ROUTERS注册遗漏、路径错误、router优先级冲突）、using()与路由的协作机制、事务中读库失效的底层原因及绕过方案，并直击select_related/prefetch_related跨库查询、ForeignKey跨库关联等高危场景的限制与替代策略，帮你避开从配置到生产的全链路“坑”。

怎么写一个能用的 DatabaseRouter 类

必须实现四个方法，少一个 Django 就会报 AttributeError: 'YourRouter' object has no attribute 'db_for_read'。实际项目里最容易漏的是 allow_relation 和 allow_migrate，不写它们，跨库 ForeignKey 或迁移命令（python manage.py migrate）直接失败。

典型结构如下：

class PrimaryReplicaRouter:
    def db_for_read(self, model, **hints):
        return 'replica'
def db_for_write(self, model, **hints):
    return 'primary'

def allow_relation(self, obj1, obj2, **hints):
    # 同库或都走 primary/replica 才允许关联
    if obj1._state.db in ('primary', 'replica') and \
       obj2._state.db in ('primary', 'replica'):
        return True
    return False

def allow_migrate(self, db, app_label, model_name=None, **hints):
    # 写库只跑迁移，读库不跑
    if db == 'replica':
        return False
    return True

注意： allow_migrate 的返回值是布尔值，不是数据库名；返回 False 表示“这个迁移不该在该 db 上执行”，不是“跳过迁移”。

为什么 settings.DATABASES 配置完还连不上 replica

光在 DATABASES 里加了 'replica' 配置项没用——Django 不会自动把查询分发过去。必须在 settings.DATABASE_ROUTERS 中显式注册路由类，否则所有操作默认走 'default'。

常见错误配置：

• 忘了加引号：DATABASE_ROUTERS = ['myapp.routers.PrimaryReplicaRouter']（字符串路径，不是类实例）
• 路径写错：比如模块不存在、类名拼错，Django 启动时不会报错，但路由完全不生效
• 多个 router 顺序冲突：后注册的 router 可能覆盖前者的 db_for_read 判断，建议只配一个 router 类，内部用逻辑分支处理

using() 和 router 冲突时谁赢

using() 优先级更高。比如 User.objects.using('replica').all() 会强制走 replica，绕过 router 的 db_for_read 判断。这在调试或特殊场景有用，但也容易掩盖路由配置问题。

容易踩的坑：

• 写了 using('replica') 却没在 DATABASES 里配 'replica' → 报错 ConnectionDoesNotExist: The connection 'replica' doesn't exist
• 在 allow_migrate 里返回 False，但又对 replica 手动执行 migrate --database=replica → 迁移被拒绝，但错误信息不明确，只显示 “No migrations to apply”
• 使用 select_related() 或 prefetch_related() 跨模型时，如果关联表在不同库，Django 无法生成合法 SQL，直接抛 DatabaseError

读写分离在事务里失效怎么办

只要进了 transaction.atomic()，Django 默认把所有读也切到写库（primary），这是硬编码行为，router 无法干预。这是为了保证事务内读写一致性，但代价是 replica 完全闲置。

如果你确定某段事务内的读可以容忍旧数据，只能手动指定：

User.objects.using('replica').filter(...)

但要注意：using() 在事务中仍有效，只是不能和 select_related 混用——后者会忽略 using 并尝试 join，而跨库 join 不被支持。

真正难处理的是带 ForeignKey 的复杂查询。一旦模型 A 和 B 分属不同库，Django 就没法安全地做关联查询，这时候得退回到原生 SQL 或应用层拆解逻辑。

今天关于《Django多数据库配置与读写分离教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！