SQLModel 原生不支持对字符串主键执行类似数据库序列（AUTO_INCREMENT）的自动填充，尤其当 ID 依赖实例字段（如 task、use_case）时；本文介绍一种安全、可维护的替代方案——通过模型方法 + 事务级 ID 生成器实现可控的自定义 ID 逻辑。
sqlmodel 原生不支持对字符串主键执行类似数据库序列（auto_increment）的自动填充，尤其当 id 依赖实例字段（如 `task`、`use_case`）时；本文介绍一种安全、可维护的替代方案——通过模型方法 + 事务级 id 生成器实现可控的自定义 id 逻辑。
在 SQLModel（基于 SQLAlchemy 和 Pydantic）中，主键字段若声明为 Field(default=None, primary_key=True)，其值必须由应用层显式提供——数据库无法像整型 SERIAL 那样自动递增字符串格式 ID。更关键的是，ID 生成逻辑若依赖其他字段（如 task 和 use_case），则必须在实例已部分初始化后才能计算，而 SQLModel 的 default 或 default_factory 无法访问实例属性，因此无法在 Field 层面直接实现该逻辑。
✅ 推荐实践：将 ID 生成解耦为显式调用的方法，并结合数据库事务保证一致性：
from typing import Optional, List
from sqlmodel import Field, SQLModel, Session, create_engine, select
from sqlalchemy import text
class Query(SQLModel, table=True):
id: Optional[str] = Field(default=None, primary_key=True)
text: str = Field(default=None, unique=True)
task: str
use_case: str
def generate_id(self, session: Session) -> str:
"""基于当前字段值与数据库最新序号生成唯一 ID"""
# 提取前缀（注意空值/长度不足处理）
prefix_task = (self.task or "")[:3].upper()
prefix_use_case = (self.use_case or "")[:3].upper()
prefix = f"{prefix_task}-{prefix_use_case}"
# 查询该前缀下最大序号（例如 'TAS-USE-102' → 102）
stmt = text("""
SELECT MAX(CAST(SUBSTRING_INDEX(id, '-', -1) AS UNSIGNED))
FROM query
WHERE id LIKE :prefix_pattern
""")
result = session.exec(stmt, {"prefix_pattern": f"{prefix}-%"}).one_or_none()
latest_num = result or 0
return f"{prefix}-{latest_num + 1}"
# 使用示例（需在事务内调用）
engine = create_engine("sqlite:///example.db")
SQLModel.metadata.create_all(engine)
with Session(engine) as session:
q = Query(task="data_extraction", use_case="reporting", text="Get monthly sales")
q.id = q.generate_id(session) # ✅ 显式生成，确保字段已赋值
session.add(q)
session.commit()
print(f"Generated ID: {q.id}") # 输出：DAT-REP-1（或更高序号）
⚠️ 注意事项：
- 事务安全：generate_id() 必须在 Session 活跃且未提交时调用，避免并发写入导致 ID 冲突（高并发场景建议加数据库锁或使用 SELECT ... FOR UPDATE）；
- 前缀健壮性：实际项目中应对 task/use_case 做非空校验与规范化（如 .strip().replace(' ', '_')），避免生成 --1 类无效 ID；
- 唯一性兜底：仍需保留数据库 UNIQUE 约束（如 text 字段已设 unique=True，也可为 id 单独加索引），防止极小概率冲突；
- 不可用于 default_factory：切勿尝试 Field(default_factory=lambda: self.generate_id(...)) —— self 在 Field 初始化时不可用，会引发 NameError。
? 总结：虽然 SQLModel 不支持“声明式自增字符串主键”，但通过显式方法 + 事务内生成 + 数据库约束兜底，既能满足业务定制需求（如 TASK-USE-123 格式），又能保障数据完整性与可测试性。这是 ORM 场景下兼顾清晰性与可靠性的标准做法。
