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 工具生態提供了更可靠的基礎。