# 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`：自动连接回收
- ✅ 自动重连：连接失效时自动重建
- ✅ 连接池自动管理

### 代码质量

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

**现在：**
```python
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()
```

## 安装依赖

```bash
cd backend
pip install -r requirements.txt
```

## 使用方式

### 获取 Session

```python
from database import db_manager

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

### 查询示例

```python
# 查询单个对象
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. 添加查询缓存（可选）