SQLAlchemy读写分离需显式配置bind路由，仅声明SQLALCHEMY_BINDS不生效；必须通过__bind_key__、get_bind()钩子或手动指定bind参数控制连接选择，否则所有操作默认走主库。
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() 方法：
立即学习“Python免费学习笔记（深入）”；
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
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 本质是写锁，却走了读库。这些边界点，光靠自动化路由兜不住。
