FlaskSQLAlchemy数据库读写分离配置教程

本文深入解析了如何在 Flask 中借助 SQLAlchemy-Bind 机制实现数据库读写分离，澄清了其并非独立第三方包，而是 Flask-SQLAlchemy 内置的多数据库绑定能力；通过合理配置 `SQLALCHEMY_DATABASE_URI`（主库写）与 `SQLALCHEMY_BINDS`（多个从库读）、显式设置模型的 `__bind_key__`，并封装安全的只读会话函数，开发者可精准控制读写流量走向，避免常见陷阱如误写从库、跨库关联查询失败或主从延迟导致的一致性问题——掌握这些核心配置与实践模式，是构建高可用、可扩展 Web 应用数据库层的关键一步。

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><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>

复杂业务里，最容易被忽略的是：主从延迟导致刚写入的数据立刻用从库查不到。这不是配置问题，是架构约束——强一致性读必须走主库。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《FlaskSQLAlchemy数据库读写分离配置教程》文章吧，也可关注golang学习网公众号了解相关技术文章。