SQLAlchemy中__tablename__必须显式声明，否则默认使用类名小写（如UserProfile→userprofile），易导致PostgreSQL等大小写敏感数据库报RelationNotFoundError；字段、外键、add()等也须严格同步数据库schema。
SQLAlchemy 中 __tablename__ 必须显式声明
不写 __tablename__，SQLAlchemy 默认用类名小写作为表名，但一旦类名含大写字母（如 UserProfile），生成的表名会是 userprofile，而非预期的 user_profile。更严重的是，某些数据库（如 PostgreSQL）对大小写敏感，隐式推导容易引发 RelationNotFoundError 或查询失败。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 始终显式定义
__tablename__ = "users"，避免依赖默认逻辑 - 若需统一加前缀（如
app_users），在基类中用__tablename__+__table_args__控制，不要靠字符串拼接 - 表名不建议用连字符（
user-info），部分方言（如 SQLite）虽支持，但 MySQL 会报语法错误
字段类型不匹配导致 OperationalError: no such column
常见于从已有数据库反向生成模型后，手动修改了字段名但没同步更新 Column 的 name 参数，或用了 nullable=False 却未设默认值，而数据库该列允许 NULL。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 字段定义必须与数据库实际 schema 严格一致：列名、类型、是否为空、默认值
- 用
Column(String(50), name="email_addr")显式绑定物理列名，尤其当 Python 变量名（email_addr）和数据库列名（email_address）不同时 - 新增非空字段时，先设
nullable=True，迁移数据后再改回False，否则alembic upgrade会因旧记录缺失值而失败
relationship() 和 backref 搞混就查不到关联数据
比如 User 类里写 posts = relationship("Post", backref="author")，本意是让 Post 自动拥有 author 属性，但如果 Post 类里没定义 user_id 外键字段，或外键指向错误表，post.author 就返回 None，且无明确报错。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 外键字段必须显式声明：
user_id = Column(Integer, ForeignKey("users.id"))，不能只靠relationship推断 - 优先用
back_populates替代backref：两边都写清楚，避免单边配置遗漏 - 调试时直接查 SQL：
print(str(session.query(User).options(joinedload(User.posts)).statement))，确认 JOIN 是否按预期生成
实例化后不 add() 就调 commit()，数据根本不会进库
新手常以为只要对象创建了、属性赋值了，调 session.commit() 就自动保存——其实 SQLAlchemy 有明确的状态机：Transient（刚 new 出来）→ Pending（add 后）→ Persistent（commit 后）。跳过 add()，对象永远卡在 Transient 状态。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 所有新对象必须显式调
session.add(obj)或session.add_all([obj1, obj2]) - 批量插入慎用
session.bulk_save_objects()：它绕过 ORM 生命周期，不触发事件、不校验、不填充默认值（如created_at） - 如果用
merge()，注意它会先查再插/更，性能开销大，仅用于“不确定是否存在”的场景
Column、每处 ForeignKey、每次 add() 都对应着底层状态流转。最易被忽略的是：数据库 schema 变更后，模型没同步更新，或者迁移脚本没跑全，这时候 ORM 会静默失败——不是报错，而是查不到、存不进、关联为空。 
