docs/v1.0/architecture/adrs/002-postgresql-17-uuid-v7.md

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. 模型定义

   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 定义

   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

迁移步骤

# 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

验证

-- 验证 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
• UUID v7 Specification (RFC 9562)
• SQLAlchemy PostgreSQL UUID Type

---

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