2026年7月5日

之前提到过，sqlite-utils 4.0rc1的发布已经过去几周了。考虑到订阅服务里Claude Fable的使用窗口只剩最后几天，决定趁这个机会看看它能不能帮我把4.0稳定版打磨到真正放心的程度——毕竟一直坚持语义化版本控制，希望不兼容的大版本越少越好。

这次从手机上的Claude Code for Web开始，给了这么个提示词：

Final review before shipping a stable 4.0 release - very important to spot any last minute things that would be a breaking change if we fix them later

它生成了第一份报告。结果发现了好几个自己还没碰到过的严重问题——Fable把它们归为5个“发布阻塞级”的bug。其中最要命的一个是：

1. delete_where() never commits and poisons the connection (data loss)

Table.delete_where() (sqlite_utils/db.py:2948) runs its DELETE via a bare self.db.execute() with no atomic() wrapper — compare Table.delete() at db.py:2944, which wraps correctly. The connection is left in_transaction=True, so every subsequent atomic() call takes the sa vepoint branch (db.py:430-440) and never commits either.

Reproduced end-to-end:

db = sqlite_utils.Database("dw.db")
db["t"].insert_all([{"id": i} for i in range(3)], pk="id")
db["t"].delete_where("id = ?", [0]) # conn.in_transaction is now True
db["t"].insert({"id": 50})
db["u"].insert({"a": 1})
db.close()
# Reopen: rows are [0, 1, 2] — the delete, row 50, AND table u are all gone.

这是个真正的大坑！幸亏没在rc1里直接发出去。虽说这种bug可以放在4.0.1补丁版里修，但总归不如稳定版就干净。

整个修复过程用了37个提示词、34次提交、跨越30个文件、增删了+1,321/-190行代码。一边处理所有反馈，一边顺带做了几项设计改进。

有意思的是，这类比较难的任务反而给了更多同时做其他事情的机会——袋里任务有时需要10到15分钟才能完成，正好可以出门逛逛Half Moon Bay的7月4日游行，隔段时间从手机上看看Fable的进度，再继续下一步。

具体细节可以看PR和共享的对话记录。最终审查切换到了笔记本电脑，通过GitHub的PR界面完成。

最重要的改动集中在事务处理上——这是前一个RC版本新增的核心特性。新RC现在包含了关于新事务模型的完整文档，引言部分直接引用如下：

Every method in this library that writes to the database—insert(), upsert(), update(), delete(), delete_where(), transform(), create_table(), create_index(), enable_fts() and the rest—runs inside its own transaction and commits it before returning. Your changes are sa ved to disk as soon as the method call finishes:

db = Database("data.db")
db.table("news").insert({"headline": "Dog wins award"})
# The new row is already sa ved - no commit() required

The same applies to raw SQL executed with db.execute()—a write statement is committed as soon as it has run.

You never need to call commit(), and you do not need to close the database to persist your changes. There are exactly two situations where you need to think about transactions:

1. You want to group several write operations together, so they either all succeed or all fail—use db.atomic().
2. You are managing a transaction yourself with db.begin(), in which case nothing is committed until you commit—the library will never commit a transaction you opened.

审查Fable的文档时——通常先看文档改动是理解整个变更的最佳方式——注意到这样一个细节：

db.atomic() and the automatic per-method transactions are designed for connections in Python's default transaction handling mode. Connections created with the Python 3.12+ sqlite3.connect(..., autocommit=True) or autocommit=False options are not supported, because commit() and rollback() beha ve differently on those connections.

坦白说，之前没认真想过sqlite-utils面对Python 3.12新增的autocommit设置会怎么反应。结果发现，“beha ve differently”意味着几乎整套测试都会失败。于是又和模型一起补上了这个缺口，确保在那些连接上库也能正常工作。

And a final review by GPT-5.5

以前觉得用一个模型去审另一个模型的输出有点玄学，不太靠谱。但事实证明这招确实管用——现在习惯性地让Anthropic最好的模型审OpenAI的成果，反过来也一样，因为已经有好几次从中发现了有价值的问题。

这次对Codex Desktop和GPT-5.5 xhigh用了如下提示词：

Review changes since the last RC. Also confirm that the changelog is up-to-date.

结果真的揪出两个值得深究的问题：

Findings

• [P1] sqlite_utils/db.py:663 db.query() now rejects non-row statements only after calling db.execute(), and sqlite_utils/db.py:705 auto-commits those writes first. So db.query("update ...") raises ValueError but the update is already committed. That is a surprising side effect for a method documented as “can only be used with SQL that returns rows.”
• [P1] sqlite_utils/db.py:672 INSERT ... RETURNING through db.query() only commits after the returned generator is fully exhausted. db.query("insert ... returning ...") without iteration, or common next(db.query(...)) usage, lea ves the transaction open and the write can be rolled back on close. This contradicts docs/changelog.rst:15 and docs/python-api.rst:232, which say it takes effect without iteration.

把这些发现扔进一个新的Fable会话，它做了实验确认了问题：

Both findings were confirmed. db.query() called self.execute() first, which auto-commits writes, and only then checked cursor.description — so db.query("update ...") committed the update before raising ValueError. And the INSERT ... RETURNING commit lived at the end of the returned generator, so it never fired unless you exhausted the iterator — next(db.query(...)) or an un-iterated call left the transaction open, contradicting what the changelog and docs promise.

修复的PR在这里，完整的Claude Code对话也在这儿。审查这段代码的过程，也让对SQLite事务语义的边缘情况有了更清晰的认识。

For an estimated (unsubsidized) cost of $149.25

之前把订阅从每月100美元升级到Claude Max的200美元/月，目的就是赶在7月7日Fablepocalypse之前，多争取一些Fable的使用额度——过了那个日期，连Max订阅者也要按API实际费用来计费。

好奇如果这次工作完全按API实际费用算会花多少钱。一开始以为这些数据拿不到，因为全程是用远程的Claude Code for Web完成的。后来意识到，可以在当前会话里运行AgentsView来估算成本：

Run "uvx agentsview --help"​ and then use that tool to calculate the cost of this session

Claude摸索着用了session list --include-children命令，给出了以下结果：

这次订阅真是物有所值！回头想想，应该更早地采用自己之前建议的策略——多拆出子任务、用更便宜的模型去做。

以下是claude.ai/settings/usage当前的截图：

手头还有好几个基于Fable的大项目在进行中，目标是在涨价前把那个Fable使用量条推到100%。

The full release notes for sqlite-utils 4.0rc2

以下是完整版RC发布说明。这次让Fable在每次改动落地时自动往“Unreleased”部分添加说明，并且一边改动一边审查。这样有个额外好处：changelog的提交历史本身就成了每个改动的摘要。

过去一直坚持手动写发布说明，但老实说，这次的结果比自己写的还要好。发布说明这类文字非常适合外包给袋里——它们需要的是乏味、可预测且准确无误。

Breaking changes:

• Write statements executed with db.execute() are now committed automatically, unless a transaction is already open in which case they join it. Previously they opened an implicit transaction that stayed open until something committed it—writes appeared to work when read on the same connection but were silently rolled back when the connection closed. Code that relied on rolling back uncommitted db.execute() writes should use the new db.begin() method to open an explicit transaction first. The transaction model is documented in full at Transactions and sa ving your changes.
• db.query() now executes its SQL as soon as it is called, rather than waiting until the returned generator is first iterated. Rows are still fetched lazily during iteration. SQL errors are now raised at the call site, statements such as INSERT ... RETURNING are executed and committed immediately without needing to iterate over their results, and passing a statement that returns no rows—previously a silent no-op—now raises a ValueError recommending db.execute() instead. A statement rejected this way is rolled back before the error is raised, so it has no effect on the database.
• Python API validation errors now raise ValueError instead of AssertionError. Previously invalid arguments—such as create_table() with no columns, transform() on a table that does not exist, or passing both ignore=True and replace=True—were rejected using bare assert statements, which are silently skipped when Python runs with the -O flag. Code that caught AssertionError for these cases should catch ValueError instead.
• table.upsert() and table.upsert_all() now raise PrimaryKeyRequired if a record is missing a value for any primary key column, or has a value of None for one. Previously such records—which can never match an existing row—were quietly inserted as brand new rows, or triggered a confusing KeyError after the insert had already taken place.
• db.enable_wal() and db.disable_wal() now raise a sqlite_utils.db.TransactionError if called while a transaction is open. Previously they would silently commit the open transaction as a side effect of changing the journal mode, breaking the rollback guarantee of db.atomic() and of user-managed transactions.
• The View class no longer has an enable_fts() method. It existed only to raise NotImplementedError, since full-text search is not supported for views—calling it now raises AttributeError instead, and the method no longer appears in the API reference. The sqlite-utils enable-fts command shows a clean error when pointed at a view.
• The no-op -d/--detect-types flag has been removed from the insert and upsert commands. Type detection has been the default for CSV/TSV data since 4.0a1, so the flag did nothing—invocations using it should simply drop it. --no-detect-types remains a vailable to disable detection.
• Database() now raises a sqlite_utils.db.TransactionError if passed a connection created with the Python 3.12+ sqlite3.connect(..., autocommit=True) or autocommit=False options. commit() and rollback() beha ve differently on those connections, which previously caused every write made by the library to be silently discarded when the connection closed.

Everything else:

• Fixed a bug where table.delete_where(), table.optimize() and table.rebuild_fts() did not commit their changes, lea ving the connection inside an open transaction. Their work—and any subsequent writes—could then be silently rolled back when the connection was closed. All three now use db.atomic(), consistent with the other write methods.
• The sqlite-utils drop-table command now refuses to drop a view, and drop-view refuses to drop a table. Previously each would silently drop the wrong type of object if the name matched. Both now exit with an error suggesting the correct command to use.
• Migrations applied by the new migrations system now run inside a transaction, together with the record of the migration ha ving been applied. If a migration raises an exception its changes are rolled back and it stays pending, so it can be safely re-applied after the error is fixed. Migrations that cannot run inside a transaction, such as those executing VACUUM, can opt out using @migrations(transactional=False)—see Migrations and transactions.
• table.upsert() and table.upsert_all() now detect the primary key or compound primary key of an existing table, so the pk= argument is no longer required when upserting into a table that already has a primary key.
• db.table(table_name).insert({}) can now be used to insert a row consisting entirely of default values into an existing table, using INSERT INTO ... DEFAULT VALUES. (#759)
• Improvements to the sqlite-utils migrate command: --stop-before values that do not match any known migration are now an error instead of being silently ignored, --stop-before now works correctly with migration files that still use the older sqlite_migrate.Migrations class, and --list is now a read-only operation that no longer creates the database file or the migrations tracking table. migrations.applied() now returns migrations in the order they were applied.
• New db.begin(), db.commit() and db.rollback() methods for taking manual control of transactions, as an alternative to the db.atomic() context manager.
• New documentation: Transactions and sa ving your changes describes how transactions work and when changes are committed, and a new Upgrading page details the changes needed to move between major versions.