多个 sqlalchemy 实例必须用不同变量名绑定，如 main_db、log_db，各自独立 init_app()、create_all() 和模型定义，避免连接混用、事务错乱及表创建错误。
多个 SQLAlchemy 实例必须用不同变量名绑定
Flask 中不能只靠一个 db = SQLAlchemy() 管理多个数据库——它内部维护单例状态，强行复用会导致连接混用、事务错乱甚至崩溃。正确做法是为每个数据库创建独立的 SQLAlchemy 实例，并用语义化变量名区分，比如 main_db、log_db。
常见错误是试图用 db.init_app(app) 多次初始化同一个实例，或把多个 SQLALCHEMY_DATABASE_URI 都塞进同一配置项里。这会让 Flask-SQLAlchemy 读取错配置，最终连到默认库或报 RuntimeError: application not registered on db instance。
- 每个实例需单独调用
init_app()，且传入对应数据库 URI 的配置前缀（如SQLALCHEMY_BINDS不适用于多实例场景） - 模型定义时必须显式指定
__bind_key__，否则默认走主库；但注意：只有在单个SQLAlchemy实例启用binds时才用这个属性，多实例下应直接继承对应实例的Model - 避免在不同实例间共享模型类——哪怕字段完全一样，也得分别定义，否则
create_all()会建错表或报InvalidRequestError: Table 'xxx' is not defined
create_all() 和 drop_all() 必须按实例分别调用
多个数据库意味着多个元数据和表空间，main_db.create_all() 只建主库的表，log_db.create_all() 才建日志库的。如果漏掉某个实例的 create_all()，运行时执行 add() 就会触发 OperationalError: no such table。
特别注意迁移工具（如 Flask-Migrate）默认只跟踪第一个 SQLAlchemy 实例。若要用 flask db migrate 管理多个库，必须为每个实例单独配置 Alembic 环境，或改用 --multidb 模式并手动维护多个 env.py。
- 生产环境部署前务必检查每个实例是否都执行过
create_all()，建议写成脚本统一触发 -
drop_all()同理，别误删其他库的表——尤其测试时容易手抖执行错实例 - 如果某库只需读取（如报表库），可跳过
create_all()，但模型仍需绑定对应实例，否则查询会走错连接池
路由和业务逻辑中必须显式选择数据库实例
没有全局默认库，每个 ORM 操作都得明确用哪个 SQLAlchemy 实例。比如 main_db.session.query(User).all() 和 log_db.session.query(AccessLog).all() 是完全隔离的会话。
容易踩的坑是写了个通用函数却忘了传入实例参数，结果所有操作都跑到了 main_db 上；或者在蓝本（Blueprint）里直接用了未绑定的 db 变量，导致应用启动时报 AttributeError: 'SQLAlchemy' object has no attribute 'session'。
- 推荐把数据库实例作为参数注入视图函数，而非从模块顶层 import —— 更易 mock 和单元测试
- 跨库事务不被支持：无法用单个
session.commit()同时提交两个库的操作，必须手动控制每个实例的commit()或rollback() - 连接池是实例级的，
main_db的pool_size不影响log_db，需按各库负载单独调优
配置项命名要严格区分，避免 SQLALCHEMY_ 前缀冲突
Flask-SQLAlchemy 默认只认 SQLALCHEMY_DATABASE_URI 和 SQLALCHEMY_TRACK_MODIFICATIONS 这类固定键名。如果你把第二个库的 URI 写成 LOG_DATABASE_URI，它不会自动被识别——必须在初始化时显式传入，不能依赖配置字典自动加载。
典型错误是把所有数据库配置都塞进 app.config，却不告诉每个 SQLAlchemy 实例该读哪个键。结果 log_db 初始化时找不到 URI，抛出 sqlalchemy.exc.ArgumentError: Could not parse rfc 1738 URL from string ''。
- 初始化时直接传 URI 字符串最稳妥：
log_db = SQLAlchemy(app, session_options={'autocommit': False}, engine_options={'pool_size': 5})，URI 从app.config['LOG_DATABASE_URI']提取 - 若坚持用配置项，确保每个实例初始化前已设置对应键，且不要重用
SQLALCHEMY_*前缀（如SQLALCHEMY_LOG_DATABASE_URI会被忽略） - 不同库的方言可能不同（比如主库用 PostgreSQL，日志库用 SQLite），
create_engine的connect_args也要按实例单独传
SQLAlchemy 实例的 engine 参数必须按各自后端特性单独设置，不能共用一套配置。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
