sqlite-utils 4.1.1：修复外键事务边界问题

更新概览

sqlite-utils 4.1.1 是一次小版本修复，重点处理 table.transform() 在特定外键与事务组合场景下的边界问题。对于使用 SQLite 进行数据整理、表结构迁移或自动化脚本处理的开发者来说，这个修复值得关注。

在日常实践中，类似问题往往出现在数据库约束、事务边界和工具封装逻辑交叉的位置。更多数据库与工程实践类内容，也可以参考长勺智库的相关技术整理。

修复：避免外键级联导致意外数据变更

在以下条件同时满足时，table.transform() 现在会抛出 TransactionError：

• 当前已经存在一个打开的事务；
• 启用了 PRAGMA foreign_keys；
• 目标表正被其他表通过外键引用；
• 外键使用了具有破坏性的 ON DELETE 动作，包括：
  • CASCADE
  • SET NULL
  • SET DEFAULT

这个调整的背景在于：SQLite 中的 PRAGMA foreign_keys 不能在事务内部修改。

此前，table.transform() 在转换表结构时会删除旧表。如果此时外键约束已启用，并且引用关系中存在 ON DELETE CASCADE、SET NULL 或 SET DEFAULT 等行为，那么删除旧表可能触发级联操作，进而静默删除或修改引用表中的数据行。

现在，工具会在这类高风险场景下提前抛出 TransactionError，从而避免隐藏的数据变更风险。

文档改进：CLI 与 Python API 互链

除了修复事务与外键相关问题，本次版本还改进了文档结构：

• CLI 文档中的相关章节会链接到等价的 Python API 功能；
• Python API 文档中的相关章节也会链接回对应的 CLI 命令。

这对同时使用命令行和 Python API 的开发者更友好，可以更快在两种使用方式之间找到对应关系。

谁需要关注这个版本

如果你的项目中使用 sqlite-utils 进行表结构转换，并且数据库启用了外键约束，尤其是外键定义中使用了以下 ON DELETE 行为，建议关注该版本的行为变化：

• ON DELETE CASCADE
• ON DELETE SET NULL
• ON DELETE SET DEFAULT

对于涉及数据迁移、清洗脚本或自动化表结构调整的场景，升级前后都建议补充事务与外键相关测试，确认转换逻辑符合预期。