TransformerLab项目工作流数据库表变更导致API故障分析

问题背景

在TransformerLab项目中，开发团队最近遇到了一个关于工作流(workflow)功能的严重问题：新创建的工作流无法在界面列表中显示。经过深入调查发现，这是由于数据库表结构变更导致的兼容性问题。

问题现象

用户在创建新工作流时，系统能够成功返回工作流ID，数据库中也确实写入了相应记录。但当用户尝试获取实验(experiment)下的工作流列表时，API返回空数组，而实际上数据库中已存在相关记录。

根本原因分析

通过数据库查询对比发现，问题的根源在于workflows表的experiment_id字段类型定义不一致：

1. 旧版数据库结构：experiment_id字段没有明确定义数据类型，被存储为字符串类型
2. 新版模型定义：在SQLAlchemy模型中，experiment_id被明确定义为整数类型(Integer)

这种不一致导致查询时类型不匹配：当API尝试用整数类型查询时，无法匹配数据库中存储的字符串类型值，从而返回空结果集。

技术细节

在旧版数据库结构中，workflows表的定义如下：

CREATE TABLE workflows (
    id INTEGER PRIMARY KEY,
    name,
    config JSON,
    status,
    current_task INTEGER,
    current_job_id INTEGER,
    experiment_id,  -- 未指定类型
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT current_timestamp
);

而在新版SQLAlchemy模型定义中：

experiment_id: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)

这种数据类型定义的变化导致了API查询失败。

影响范围

此问题会影响所有在数据库结构变更前创建的环境。具体表现为：

1. 新工作流可以创建成功并写入数据库
2. 工作流列表API无法返回已创建的工作流
3. 工作流与实验的关联关系无法正常建立

解决方案

针对此问题，建议采取以下解决方案：

1. 数据库迁移：编写并执行数据库迁移脚本，将现有数据库中的experiment_id字段从字符串类型转换为整数类型
2. 数据修复：对于已存在的数据，需要进行批量更新，确保所有experiment_id值都转换为整数
3. 版本兼容：在API层添加类型转换逻辑，确保新旧数据格式都能正确处理

预防措施

为避免类似问题再次发生，建议：

1. 严格的数据库变更管理：所有数据库结构变更都应通过正式的迁移脚本进行
2. 版本兼容性测试：在发布新版本前，测试新旧数据格式的兼容性
3. 文档记录：详细记录数据库结构变更历史，便于问题排查

总结

数据库表结构变更是一项需要谨慎处理的工作。TransformerLab项目中遇到的这个问题展示了数据类型定义不一致可能导致的严重后果。通过这次经验，开发团队应建立更完善的数据库变更流程，确保系统的稳定性和数据的一致性。