Flask中必须用Flask-SQLAlchemy而非原生SQL拼接，SQLALCHEMY_DATABASE_URI需正确处理协议、编码及特殊字符，db.create_all()须在app_context中执行且确保模型已导入，session操作必须显式commit或rollback，多线程需独立上下文。
直接用原生 SQL 拼接字符串操作数据库，在 Flask 里等于裸奔——SQL injection 风险极高，且事务、连接池、模型复用全得自己扛。Flask-SQLAlchemy 不是“可选插件”，而是当前 Flask 生态下最稳妥的数据库集成方式。
SQLALCHEMY_DATABASE_URI 怎么写才不翻车
这个配置项写错，应用启动就报 sqlalchemy.exc.NoSuchModuleError 或连上库却查不到表。关键点不在语法，而在协议前缀、编码和特殊字符处理：
-
sqlite:///./app.db：路径用三个斜杠，相对路径前面加./，否则可能被解析成绝对路径 -
mysql+pymysql://root:%40pwd123@localhost:3306/mydb：密码含@、/、:等字符时，必须用urllib.parse.quote_plus()编码，不能手动替换 -
postgresql+psycopg2://user:pass@host/dbname?client_encoding=utf8：PostgreSQL 建议显式加client_encoding参数，避免中文入库乱码 - 别在 URI 里写
?charset=utf8mb4（MySQL）或?sslmode=disable（PostgreSQL）后不加空格或引号——Flask 配置解析器会截断
db.create_all() 为什么有时不建表
常见现象：模型类已定义、db = SQLAlchemy(app) 已执行、也调了 db.create_all()，但数据库里还是没表。根本原因通常是上下文缺失或模型未被导入：
- 必须在
app.app_context()内执行：with app.app_context(): db.create_all() - 模型文件（如
models.py）没被 import 进主应用模块——Python 不会自动加载未引用的模块，db.create_all()看不到那些类 - 模型继承自
db.Model，但db实例化晚于模型定义（比如先写class User(db.Model)，再写db = SQLAlchemy()）→ 报AttributeError: 'SQLAlchemy' object has no attribute 'Model' - SQLite 路径目录不存在（如
./instance/app.db），create_all()不报错但也不建库——得提前os.makedirs(os.path.dirname(db_path), exist_ok=True)
session.add() 后不 commit 就返回，数据去哪了
这是新手最常踩的坑：对象加进 session，函数返回了，数据库里却查不到。本质是事务没提交，且 session 在请求结束时被丢弃：
-
db.session.add(user)只是把对象标记为“待插入”，真正写入靠db.session.commit() - 漏掉
commit()→ 数据只在当前 session 缓存中，请求结束自动 rollback - 写了
commit()但抛了异常没捕获 → 事务中断，后续语句不执行，且 session 处于 invalid 状态，再调add()会报InvalidRequestError - 正确模式：
try: db.session.add(user) db.session.commit() except Exception: db.session.rollback() raise - 别依赖
autocommit=True（Flask-SQLAlchemy 不支持该参数），它只存在于底层 SQLAlchemy 的 Engine 配置中，与 Flask-SQLAlchemy 的 session 层无关
多线程/异步环境下 session 复用的陷阱
在 Celery 任务、后台线程或 FastAPI + Flask 混合场景中，直接复用主线程的 db.session 会导致 DetachedInstanceError 或数据错乱：
-
db.session默认是 request-scoped，只在当前 Flask 请求生命周期内有效；脱离请求上下文（如线程、定时任务）后，session 已关闭 - 不要在子线程里用
db.session.add()—— 即使加了app.app_context()，不同线程的 session 对象也不能共享 - 正确做法：每个线程/任务内重新创建干净 session：
from app import db with db.app_context(): # 此处 db.session 是新实例 user = User.query.get(1) user.status = 'processed' db.session.commit() - 更健壮的方式是用
scoped_session手动管理，但 Flask-SQLAlchemy 默认已封装好，只需确保每次操作都在独立上下文中
模型定义和 session 生命周期这两个地方，最容易被当成“写完就能跑”而忽略细节。一旦出问题，错误信息往往不指向真实原因——比如 no such table 其实是模型没导入，object is not attached to a session 其实是跨了请求上下文。盯住上下文和导入链，比查文档更快定位。
