# ADR 002: 升级 PostgreSQL 17 使用原生 UUID v7

> **状态**: 已实施  
> **创建日期**: 2025-01-18  
> **决策者**: 架构团队

---

## 背景

项目初期使用 PostgreSQL 14 + Python `uuid-utils` 库生成 UUID v7。虽然可行，但存在以下问题：

1. **应用层依赖**：ID 生成逻辑在 Python 层，增加应用复杂度
2. **类型不匹配**：SQLModel 使用 `str` 类型，数据库存储为 `VARCHAR`，索引性能未达最优
3. **未来趋势**：PostgreSQL 17 已原生支持 `gen_uuid_v7()`

## 决策

**升级到 PostgreSQL 17，使用数据库原生 UUID v7 生成**

### 技术方案

1. **数据库升级**
   - Docker: `postgres:14-alpine` → `postgres:17-alpine`
   - 原生函数: `gen_uuid_v7()` (无需扩展)

2. **模型定义**

   ```python
   from uuid import UUID
   from sqlalchemy import Column, text
   from sqlalchemy.dialects.postgresql import UUID as PG_UUID

   id: UUID = Field(
       sa_column=Column(
           PG_UUID(as_uuid=True),
           primary_key=True,
           server_default=text("gen_uuid_v7()")
       )
   )
   ```

3. **Schema 定义**

   ```python
   from uuid import UUID

   class UserResponse(BaseModel):
       user_id: UUID  # 替代 str
   ```

4. **依赖清理**
   - 移除: `uuid-utils==0.9.0`
   - 保留: `app/core/id_generator.py`（备用/测试）

## 优势

| 维度       | 改进                                            |
| ---------- | ----------------------------------------------- |
| **性能**   | UUID 列类型 + B-tree 索引，查询性能优于 VARCHAR |
| **可靠性** | 数据库层面保证 ID 生成，无应用层故障风险        |
| **简洁性** | 减少 Python 依赖，代码更简洁                    |
| **标准化** | 使用 PostgreSQL 原生特性，符合最佳实践          |
| **未来性** | PostgreSQL 17+ 长期支持，无需维护自定义逻辑     |

## 劣势与风险

| 风险               | 缓解措施                                   |
| ------------------ | ------------------------------------------ |
| PostgreSQL 17 较新 | 开发阶段无影响；生产环境需确认云服务商支持 |
| 迁移成本           | 开发阶段数据量小，直接重建表即可           |
| 兼容性             | 保留 `id_generator.py` 作为备用方案        |

## 实施细节

### 变更文件

- ✅ `server/docker-compose.yml`: 升级镜像版本
- ✅ `server/app/models/user.py`: UUID 类型 + `server_default`
- ✅ `server/app/models/folder.py`: UUID 类型 + `server_default`
- ✅ `server/app/schemas/user.py`: UUID 类型
- ✅ `server/app/schemas/folder.py`: UUID 类型
- ✅ `server/requirements.txt`: 移除 `uuid-utils`

### 迁移步骤

```bash
# 1. 停止并删除旧容器
cd server
docker-compose down -v

# 2. 拉取新镜像
docker-compose pull postgres

# 3. 重建数据库
python -m app.migrations.001_uuid_migration

# 4. 启动服务
docker-compose up -d
```

## 验证

```sql
-- 验证 PostgreSQL 版本
SELECT version();
-- 应显示: PostgreSQL 17.x

-- 验证 UUID v7 函数
SELECT gen_uuid_v7();
-- 应返回: 019d1234-5678-7abc-def0-123456789abc

-- 验证列类型
\d users
-- id 列应为: uuid (not null, default gen_uuid_v7())
```

## 后续工作

1. **生产环境评估**：确认云服务商（阿里云 RDS、AWS RDS）对 PostgreSQL 17 的支持情况
2. **性能测试**：对比 UUID vs VARCHAR 的索引性能
3. **监控告警**：添加 ID 生成失败的监控

## 参考资料

- [PostgreSQL 17 Release Notes](https://www.postgresql.org/docs/17/release-17.html)
- [UUID v7 Specification (RFC 9562)](https://datatracker.ietf.org/doc/html/rfc9562)
- [SQLAlchemy PostgreSQL UUID Type](https://docs.sqlalchemy.org/en/20/dialects/postgresql.html#sqlalchemy.dialects.postgresql.UUID)

---

**决策结果**: ✅ 已实施，开发环境运行正常