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