FlaskSQLAlchemy读写分离配置教程

本文深入剖析了 Flask-SQLAlchemy 实现读写分离的核心原理与常见陷阱，强调配置 `SQLALCHEMY_BINDS` 仅注册连接池而不自动路由，必须通过模型级 `__bind_key__`、查询级 `bind` 参数或全局 `get_bind()` 钩子显式控制流量分发；同时揭示了动态路由的本质是基于查询类型（如 `SELECT`）和模型绑定策略的精准判断，而非装饰器或中间件；更关键的是警示开发者：读库模型严禁用于写操作、跨 bind 联合查询会失败、表结构需手动同步、连接对象不可缓存，并直击业务中易被忽视的边界场景——如 `SELECT FOR UPDATE` 和 `INSERT ... ON DUPLICATE KEY UPDATE` 的读写定性问题，真正把读写分离从“能跑”推向“可靠、高效、可维护”的生产级实践。

SQLAlchemy binds 配置必须显式声明读库，否则所有操作都走默认库

Flask-SQLAlchemy 的 binds 只是「命名连接池」的注册表，不带路由逻辑。你得手动告诉 SQLAlchemy：哪些模型或查询该用哪个 bind。默认情况下，哪怕你配了 binds={'read': 'mysql://...'}，User.query.all() 依然走 SQLALCHEMY_DATABASE_URI 对应的主库（写库）。

常见错误是以为配完 binds 就自动分流——其实只是多挂了几条数据库连接，没写路由代码，读请求照样打到写库。

• 在 create_app() 中配置 SQLALCHEMY_BINDS 字典，key 是 bind 名（如 'read'），value 是数据库 URL
• 每个需要走读库的模型，必须显式指定 __bind_key__ = 'read'
• 如果用原生 db.session.execute()，需传 bind='read' 参数，否则默认用主库
• __bind_key__ 不继承，子类要重写；联合查询（join）跨 bind 会报错，禁止混用

动态路由分发靠 get_bind()，不是装饰器也不是中间件

SQLAlchemy 本身提供 get_bind() 钩子，它是唯一可靠的、能按查询类型（SELECT/INSERT/UPDATE/DELETE）或模型类决定用哪个连接的地方。别试图在视图函数里手动切换 db.engine 或 patch session.bind —— 线程不安全，且和 Flask-SQLAlchemy 的 session 生命周期冲突。

正确做法是在 SQLAlchemy 实例化后，覆盖其 get_bind() 方法：

def get_bind(self, mapper=None, clause=None):
    if mapper is not None:
        if hasattr(mapper.class_, '__bind_key__') and mapper.class_.__bind_key__ == 'read':
            return self.get_engine(bind='read')
    if clause is not None and isinstance(clause, sqlalchemy.sql.selectable.Select):
        return self.get_engine(bind='read')
    return self.get_engine()

注意：这个函数在每次查询生成时调用，所以不能做耗时操作；clause 是原始 SQL AST，不是字符串，判断 SELECT 要用 isinstance(..., Select)，别用 str(clause).startswith('SELECT')。

写操作误进读库？检查 session.flush() 前是否被 get_bind() 错判

最隐蔽的问题是：你给模型设了 __bind_key__ = 'read'，但后续又对它做了 db.session.add() 或 .delete() —— 这些写操作仍会发往读库，导致报错 ERROR 1290 (HY000): The MySQL server is running with the --read-only option。

• 读库模型只用于查询，不要实例化后塞进 session 做增删改
• 如果业务需要“先查后改”，必须用主库模型（无 __bind_key__ 或设为 'default'）重新查一遍
• Flask-SQLAlchemy 的 db.create_all() 默认只在主库建表；读库表结构要单独同步，不然 __bind_key__ 模型会报 no such table
• 使用 db.reflect(bind='read') 可检查读库表是否存在，避免上线后才发现 schema 不一致

Flask 请求上下文里不能缓存 engine 或 connection

有人想优化性能，在 g 或全局变量里存 db.get_engine('read')，这是危险的。SQLAlchemy 的 Engine 本身是线程安全的，但它的底层连接（Connection）不是。Flask 多 worker（gunicorn）或多线程模式下，复用 connection 会导致事务混乱、连接超时甚至数据错乱。

正确姿势是始终通过 db.get_engine() 或 db.session.bind 获取连接，让 SQLAlchemy 自己管理连接池。如果你看到慢查询集中在 get_engine()，问题不在这里，而在 DNS 解析、连接池过小或网络延迟——该调 pool_size 和 pool_recycle，而不是绕过它。

读写分离真正难的不是配 binds，而是厘清「什么算读」「什么算写」——比如 INSERT ... ON DUPLICATE KEY UPDATE 算写，但有人误当读；又比如 SELECT FOR UPDATE 本质是写锁，却走了读库。这些边界点，光靠自动化路由兜不住。

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