Tolan/backend/文档/SQLAlchemy迁移说明.md

SQLAlchemy 迁移说明

迁移概述

项目已从手动 SQL 查询迁移到 SQLAlchemy ORM，解决了连接管理问题。

迁移内容

1. 新增文件

文件	说明
backend/models_db.py	SQLAlchemy 模型定义（User, Message, ConversationSummary）
backend/文档/SQLAlchemy迁移说明.md	本文档

2. 修改文件

文件	改动内容
backend/requirements.txt	添加 sqlalchemy[asyncio]==2.0.23
backend/database.py	重构为使用 SQLAlchemy 连接池和 Session
backend/services/user_service.py	所有 SQL 查询改为 ORM
backend/services/message_service.py	所有 SQL 查询改为 ORM
backend/services/context_service.py	所有 SQL 查询改为 ORM
backend/services/summary_service.py	所有 SQL 查询改为 ORM

核心改进

连接管理

之前（手动管理）：

• 手动实现连接池
• 手动实现健康检查
• 手动实现重连机制

现在（SQLAlchemy 自动管理）：

• ✅ pool_pre_ping=True：自动健康检查
• ✅ pool_recycle=7200：自动连接回收
• ✅ 自动重连：连接失效时自动重建
• ✅ 连接池自动管理

代码质量

之前：

query = "SELECT * FROM users WHERE user_id = %(user_id)s"
user = await db_manager.execute_one(query, {"user_id": user_id})

现在：

async with db_manager.get_session() as session:
    result = await session.execute(
        select(User).where(User.user_id == user_id)
    )
    user = result.scalar_one_or_none()

安装依赖

cd backend
pip install -r requirements.txt

使用方式

获取 Session

from database import db_manager

async with db_manager.get_session() as session:
    # 使用 session 进行数据库操作
    user = await session.get(User, user_id)

查询示例

# 查询单个对象
user = await session.get(User, user_id)

# 查询列表
result = await session.execute(
    select(Message)
    .where(Message.user_id == user_id)
    .order_by(Message.created_at.desc())
)
messages = result.scalars().all()

# 更新
await session.execute(
    update(User)
    .where(User.user_id == user_id)
    .values(username="new_name")
)
await session.commit()

配置说明

SQLAlchemy 连接池配置（在 database.py 中）：

• pool_size=10：连接池大小
• max_overflow=20：最大溢出连接数
• pool_pre_ping=True：自动健康检查（关键）
• pool_recycle=7200：连接回收时间（2小时）

注意事项

1. Session 管理：必须使用 async with db_manager.get_session() as session 确保 Session 正确关闭
2. 事务提交：修改操作后需要 await session.commit()
3. 类型安全：ORM 提供类型提示，减少错误

性能对比

指标	之前	现在
连接管理	手动实现	✅ 自动管理
健康检查	手动实现	✅ 自动检测
代码维护性	SQL 分散	✅ 模型集中
类型安全	无	✅ 有类型提示

后续优化建议

1. 添加数据库迁移工具（Alembic）
2. 优化查询性能（添加索引、使用 select_related）
3. 添加查询缓存（可选）