flask-sqlalchemy的sqlalchemy_binds仅注册命名连接池，不自动路由；必须通过模型__bind_key__显式指定或查询时传bind参数，否则默认走sqlalchemy_database_uri主库。
Flask SQLALCHEMY_BINDS 是怎么决定用哪个数据库的
不是靠“自动识别模型”，而是靠你显式指定绑定名。Flask-SQLAlchemy 不会根据表名或模型类名自动查 SQLALCHEMY_BINDS 字典，必须在模型定义时用 __bind_key__ 声明，或者在查询时手动调用 bind 参数。
常见错误是只配了 SQLALCHEMY_BINDS 却没给模型设 __bind_key__，结果所有操作仍走默认库（None 绑定）。
-
__bind_key__ = 'users'：该模型所有 CRUD 都路由到SQLALCHEMY_BINDS['users']对应的 URL - 没设
__bind_key__的模型，一律走主数据库（即SQLALCHEMY_DATABASE_URI） - 同一个模型不能动态切换 bind；要切换，得用原生
session.execute+bind参数
如何让一个 Model 同时支持主库和多个 bind 库
不能靠单个模型类“自动适配”，但可以用继承+类工厂或运行时绑定控制。最稳妥的做法是为每个目标库定义独立模型类，哪怕字段完全一样。
比如用户数据分片在 users_shard_01 和 users_shard_02，就该写两个类：
class UserShard01(db.Model):
__bind_key__ = 'users_shard_01'
id = db.Column(db.Integer, primary_key=True)
name = db.Column(db.String(50))
<p>class UserShard02(db.Model):
__bind_key__ = 'users_shard_02'
id = db.Column(db.Integer, primary_key=True)
name = db.Column(db.String(50))
</p>
- 别试图用一个
User类通过修改__bind_key__属性来切换——类属性改了会影响全局所有实例 - 如果真要动态选库（如按 user_id 取模），应在业务逻辑层判断后，再调用对应模型类，而不是在 ORM 层“路由”
- 迁移时注意：
flask db migrate默认只扫主库模型；多 bind 模型需用--multidb并配合env.py中的target_metadata分离处理
执行原生 SQL 时如何指定 bind 而不依赖模型
当你要绕过模型、直接发语句到某个库（比如做跨库 join、DDL 或临时统计），就得用 db.session.execute 显式传 bind。
这个 bind 参数值不是字符串名，而是 db.get_engine(app, bind='xxx') 返回的引擎对象。
from sqlalchemy import text
<p>engine = db.get_engine(current_app, bind='analytics')
result = db.session.execute(text('SELECT COUNT(*) FROM events'), bind=engine).scalar()
</p>
- 错写成
bind='analytics'会报InvalidRequestError: No engine for bind analytics -
db.session.connection(bind=...)也行，但execute更直观；注意它不自动 commit，需手动db.session.commit()（除非用autocommit=Truesession） - 这种写法绕过了 Flask-SQLAlchemy 的 session 绑定逻辑，适合 ad-hoc 场景，但别在事务中混用不同 bind 的 ORM 操作——会出隔离问题
为什么 db.create_all() 不建 bind 库的表
因为 create_all 默认只作用于主库引擎。它内部调用的是 metadata.create_all(db.engine)，而 db.engine 永远是主库。
要建 bind 库的表，必须显式传对应引擎：
db.create_all(bind='users') # ✅ 正确：传 bind 名 db.create_all(bind=db.get_engine(app, bind='users')) # ✅ 等价
- 传字符串名是 Flask-SQLAlchemy 的封装逻辑；传引擎对象是 SQLAlchemy 原生行为
-
create_all(bind=None)等价于不传 bind，仍是主库 - 生产环境慎用
create_all—— 它不会删旧表、不会改结构，仅“补漏”，且无法处理 bind 库间外键等约束
多 bind 的真实复杂点不在配置，而在事务边界和连接复用：Flask-SQLAlchemy 的 session 是单引擎绑定的，没法天然支持跨 bind 事务。需要跨库原子性，得上两阶段提交或应用层补偿，不是加几个配置能解决的。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
