sqlite-utils 4.0 发布：新增数据库模式迁移功能

sqlite-utils 4.0 正式发布，这是该项目的第 124 个版本，也是自 2020 年 11 月 3.0 以来的首次大版本更新。除了小幅破坏性变更（见升级指南），新版本引入了三项主要特性：数据库模式迁移、嵌套事务（通过新的 db.atomic() 方法）以及复合外键支持。

数据库模式迁移

模式迁移定义了一系列对 SQLite 数据库的变更操作，并跟踪已应用的迁移状态。迁移文件使用 Python 编写，依赖 sqlite-utils 库的 table.transform() 方法，该方法实现了 SQLite 文档推荐的重建表模式：创建新临时表、复制数据、删除旧表并重命名。

示例迁移文件如下（创建 creatures 表、添加列、修改列类型）：

from sqlite_utils import Migrations

migrations = Migrations("creatures")

@migrations()
def create_table(db):
    db["creatures"].create(
        {"id": int, "name": str, "species": str},
        pk="id",
    )

@migrations()
def add_weight(db):
    db["creatures"].add_column("weight", float)

@migrations()
def change_column_types(db):
    db["creatures"].transform(types={"species": int, "weight": str})

运行 uvx sqlite-utils migrate data.db migrations.py 后，数据库会创建 _sqlite_migrations 表跟踪迁移历史，并生成最终模式。--list 参数可查看已应用和待应用的迁移列表。

嵌套事务支持

长久以来，sqlite-utils 的事务处理较为混乱。新版本通过 db.atomic() 上下文管理器解决了这一问题，内部利用 SQLite 的 savepoint 机制实现嵌套事务，提高了迁移系统的安全性和可推理性。

复合外键

复合外键支持包括创建、转换和自省。该功能源于代码审查，Claude Fable 5 帮助设计了符合库整体风格的 API。

其他重要变更

• Upsert 改用 INSERT ... ON CONFLICT ... DO UPDATE SET 语法，自动检测主键并拒绝缺少必需主键值的记录。
• db.query() 立即执行并拒绝不返回行的语句；写操作和 DDL 应使用 db.execute()。
• CSV/TSV 导入默认检测列类型（文本、整数、实数），同时保留现有表的列类型。
• table.extract() 和 extracts= 不再为全空值创建查找表记录。

AI 的贡献

升级指南和发布说明由 Claude Fable 5、Claude Opus 4.8 和 GPT-5.5 编写。作者表示，这类文档适合外包给 AI，因为它们只需准确详细，无需表达观点。

Claude Fable 5 在测试中编写了 12 个脚本，发现了 4 个发布阻塞问题和 10 个额外 bug，例如事务隐式提交、查询解析漏洞、复合外键排序错误等。这些发现显著提高了 4.0 版本的质量。

总的来说，sqlite-utils 4.0 通过迁移系统、事务改进和 AI 辅助测试，为 SQLite 工具生态提供了更可靠的基础。