2026-06-21 23:35 UTCOriginal source4 min readUpdated: 2026-06-30 13:03 UTC

sqlite-utils 4.0rc1 adds migrations and nested transactions

Summary

sqlite-utils 4.0rc1, the first release candidate for v4, introduces built-in database migrations and nested transactions via db.atomic(), along with several minor breaking changes.

SourceSimon Willison's Weblog

Report an error

The correction channel is not available yet. You can copy the article reference below for later.

Correction instructions

Read article

sqlite-utils 4.0rc1 adds migrations and nested transactions

Simon Willison’s Weblog

sqlite-utils 4.0rc1 adds migrations and nested transactions

21st June 2026

sqlite-utils is my combined Python library and CLI tool for working with SQLite databases. It provides an extensive set of higher-level operations on top of Python’s default sqlite3 package, including support for complex table transformations, automatic table creation from JSON data and a whole lot more.

I released sqlite-utils 4.0rc1, the first release candidate for sqlite-utils v4. The major version bump indicates some (minor) backwards incompatible changes, so I’m interested in having people try this out before I commit to a stable release.

New feature: migrations

There are two significant new features in this RC compared to the previous 4.0 alphas.

The first is support for database migrations. This isn’t a completely new implementation—it’s a slightly modified port of the sqlite-migrate package I released a few years ago. I think that package has proved itself over time, so I’m now ready to bundle it with sqlite-utils directly.

Here’s what a set of migrations in a migrations.py file looks like:

from sqlite_utils import Database, 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)

This defines a set of two migrations, one creating the creatures table and another adding a column to it.

You can then run those migrations either using Python:

db = Database("creatures.db") migrations.apply(db)

Or with the command-line migrate command:

sqlite-utils migrate creatures.db migrations.py

The system is deliberately small: it doesn’t provide reverse migrations, so any mistakes you make should be fixed by deploying a fresh migration to undo them.

Its predecessor has been used by LLM and various other projects for several years, so I’m confident that the design is stable and works well.

The new migrations feature is documented here.

New feature: db.atomic() transactions

This feature is a lot less exercised than migrations, so it deserves more attention from testers.

Previously, sqlite-utils mostly left transaction management up to its users, via a with db.conn: construct that reused the sqlite3 mechanism directly.

SQLite supports nested transactions in the form of savepoints, so I wanted an abstraction that could make those as easy to use as possible.

I borrowed the terminology “atomic” from Django and Peewee. Here’s what the new API looks like:

with db.atomic(): db.table("dogs").insert({"id": 1, "name": "Cleo"}, pk="id") try: with db.atomic(): db.table("dogs").insert({"id": 2, "name": "Pancakes"}) raise ValueError("skip this one") except ValueError: pass db.table("dogs").insert({"id": 3, "name": "Marnie"})

Article intelligence

EngineersAdvanced

Key points

New database migration system, ported from sqlite-migrate. No reverse migrations. Works via Python or CLI.
New db.atomic() context manager for nested transactions using SQLite savepoints.
Breaking changes: upsert behavior, default float type to REAL, double-quote identifiers, dropped Python 3.8, and more.
Call to test the RC and report issues before stable release.

Highlights and analysis are generated automatically and may contain errors. Check the original source.