SQLAlchemy、Alembic 导入或迁移失败：先保住本地数据

先分清错误处于哪一层

SQLAlchemy 是数据库工具库；Alembic 用修订文件确定迁移操作的顺序。Python 模块缺失、DBAPI 操作失败和 Alembic 找不到修订号，排查路径不同。SQLAlchemy 文档指出，OperationalError 的驱动原始信息很重要：连接中断、数据源不可用、事务失败等都可能属于此类，不能仅凭异常名认定应删除数据库。SQLAlchemy 概览 SQLAlchemy 错误说明 Alembic 教程

修改前先保住数据

1. 确认数据库属于 ComfyUI、某个自定义节点，还是启动器。记录应用版本、数据库位置或脱敏后的连接目标、完整错误和当前迁移修订号；不要公开含密码的连接串。

2. 改动依赖、版本表或结构前，按所属应用的文档做备份。应与应用协调取得一致快照；只复制正在使用的数据库文件，不能默认当成可恢复备份。先在隔离副本上试恢复，并记录原有数据的数量或标识。

3. 如果是导入缺包，检查真正启动该应用的 Python 环境及其依赖声明：

python -m pip show SQLAlchemy alembic

这条命令只盘点环境，不会修复。遇到 OperationalError，保留驱动报错，检查实际连接目标、可用性、权限与失败操作，不猜单一原因。遇到 Can't locate revision，对照数据库记录的修订号与同一应用版本附带的迁移文件；对应用自有的迁移环境，可用 Alembic current 与 history 辅助检查。SQLAlchemy 错误说明 Alembic 教程

4. 不要用 stamp head 把升级失败伪装成完成。Alembic 文档明确说明 stamp 只更改修订表而不执行迁移，upgrade 才沿迁移路径执行操作。只有所属应用的正式恢复流程，才能作为修改修订状态或重建数据库的依据。Alembic 命令

复查与边界

在隔离的恢复副本中检查旧记录仍可读取，相关应用操作正常；适合时再做受控写入。迁移命令退出码为零，不足以证明原数据完整。本文未确定你设备上的数据库归属，也不授权删库、盲目降级或改表。

资料复核：2026-09-26。本站未在本地执行数据库迁移、恢复或 GPU 复现。

相关排查

• 修复 ComfyUI 前后该记什么：一份可复查的环境记录
• ComfyUI 教程里的命令该粘到哪里？PowerShell、CMD、虚拟环境分开看