sqlalchemy-bind 是 flask-sqlalchemy 的多数据库绑定机制，非独立包；它通过 sqlalchemy_binds 配置字典定义多个数据库连接，并由模型的 __bind_key__ 显式指定归属，未声明者默认使用 sqlalchemy_database_uri 所指主库。
SQLAlchemy-Bind 是什么，为什么不能直接用 db = SQLAlchemy(app)
Flask 中默认的单实例 SQLAlchemy 只能绑定一个数据库 URL，无法区分读/写流量。读写分离需要至少两个连接池：一个主库（写 + 强一致性读），多个从库（只读 + 最终一致性读）。SQLAlchemy-Bind 并不是一个独立包，而是指 SQLAlchemy 的 binds 配置机制——它允许你为不同模型或查询显式指定使用哪个数据库连接。
常见错误是以为装个第三方包就能自动分流，其实核心靠配置 + 手动路由。
-
binds是 Flask-SQLAlchemy 的字典配置项，键为 bind 名（如'slave1'），值为数据库 URL 或引擎对象 - 模型类需通过
__bind_key__显式声明归属，否则走默认 bind（即None） - 不声明
__bind_key__的模型，即使配置了多个 bind，也只会用默认库
如何配置多 bind：主库写、从库读
在 Flask 应用初始化阶段配置 SQLALCHEMY_BINDS，并确保每个 bind 有独立连接参数（尤其注意 pool_pre_ping=True 和超时设置）。
app.config['SQLALCHEMY_DATABASE_URI'] = 'mysql+pymysql://user:pass@master:3306/main' # 默认写库
app.config['SQLALCHEMY_BINDS'] = {
'slave1': 'mysql+pymysql://user:pass@slave1:3306/main?charset=utf8mb4',
'slave2': 'mysql+pymysql://user:pass@slave2:3306/main?charset=utf8mb4'
}
app.config['SQLALCHEMY_ENGINE_OPTIONS'] = {
'pool_pre_ping': True,
'pool_recycle': 3600,
'pool_timeout': 10
}
关键点：
- 主库 URL 必须设为
SQLALCHEMY_DATABASE_URI，这是默认 bind（None），所有未指定__bind_key__的模型都走这里 - 从库 URL 建议加
?read_only=1（MySQL 8.0+）或在连接后执行SET SESSION TRANSACTION READ ONLY（需自定义 engine 事件） - 避免在
SQLALCHEMY_BINDS中重复配置主库，否则可能意外路由到从库
怎么让查询自动走从库？别依赖装饰器或中间件
Flask-SQLAlchemy 没有内置“读请求自动发从库”机制。所谓“自动”，本质是开发者控制 session.bind 或构造 Query 时指定 bind。最可靠的方式是封装一个只读查询函数，强制使用从库引擎：
from sqlalchemy import create_engine
from flask_sqlalchemy import SQLAlchemy
<p>db = SQLAlchemy(app)</p><div class="aritcle_card flexRow artxards">
<div class="artcardd flexRow">
<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill8551" title="Claw Code Suite (Python-Only Edition)"><img
src="https://img.php.cn/upload/skill/000/000/081/179212160094080.jpg" alt="Claw Code Suite (Python-Only Edition)" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a rel="nofollow" href="/xiazai/skill8551" title="Claw Code Suite (Python-Only Edition)" class="overflowclass">Claw Code Suite (Python-Only Edition)</a>
<p class="overflowclass">仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...</p>
</div>
<a rel="nofollow" href="/xiazai/skill8551" title="Claw Code Suite (Python-Only Edition)" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
</a>
</div>
</div><p>def get_slave_session(bind_key='slave1'):
engine = db.get_engine(app, bind=bind_key)
return db.create_scoped_session(options={'bind': engine})()</p><h1>使用示例</h1><p>session = get_slave_session('slave1')
users = session.query(User).filter(User.active == True).all()
session.close()</p>
常见陷阱：
- 不要 monkey patch
db.session，会导致事务混乱和连接泄漏 - 避免在视图中混用
db.session（主库）和自定义 slave session，容易误写入从库 - 如果用了
flask-sqlalchemy的db.Model.query类接口，它永远走默认 bind，必须改用session.query()
写操作出错但读正常？检查 __bind_key__ 和事务边界
典型现象：User.query.get(1) 能查到数据，但 user.name = 'new'; db.session.commit() 报 InvalidRequestError: This Session has no transaction 或写不进主库。
原因通常是模型绑错了 bind：
- 如果
User.__bind_key__ = 'slave1'，那它只能读，不能写（从库只读） - 如果忘了设
__bind_key__，但又用了db.session，它会走默认库（主库），此时写是 OK 的；但如果误用了get_slave_session()做写操作，就会失败 - 跨 bind 的关联查询（如
user.posts）会报错，因为 SQLAlchemy 不支持 join 多 bind 表
正确做法：
class User(db.Model):
__tablename__ = 'users'
__bind_key__ = None # 明确走默认库（主库），可读可写
<p>class Log(db.Model):
<strong>tablename</strong> = 'logs'
__bind_key__ = 'slave1' # 只读表，不参与写</p>
复杂业务里，最容易被忽略的是：主从延迟导致刚写入的数据立刻用从库查不到。这不是配置问题，是架构约束——强一致性读必须走主库。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
