What is new in sqlite-utils 4.0?

sqlite-utils 4.0 adds three headline features: a database migrations system (sqlite_utils.Migrations plus a sqlite-utils migrate CLI), nested transactions through the new db.atomic() context manager, and full compound (multi-column) foreign-key support. Upserts now use SQLite's ON CONFLICT syntax and CSV/TSV imports detect column types by default.

How do sqlite-utils migrations work?

sqlite-utils 4.0 migrations are Python files applied in order by the sqlite-utils migrate CLI. The library logs each applied migration in an internal _sqlite_migrations table so re-running the command only executes new ones. Each migration runs inside a db.atomic() block, so a failure rolls the whole step back cleanly.

Is sqlite-utils 4.0 backwards-compatible with 3.x scripts?

sqlite-utils 4.0 is a major version and includes breaking changes: db.query() now executes immediately and rejects non-row-returning statements (use db.execute() for writes and DDL), and column-name matching is case-insensitive. Simon Willison's release notes link to a dedicated upgrade guide covering the migration path from 3.x.

How does sqlite-utils compare to an ORM like Django or SQLAlchemy?

sqlite-utils 4.0 deliberately stays a thin toolkit around SQLite rather than a full ORM. It promotes programmatic table creation via table.transform() instead of model classes, so 4.0's migration system tracks raw SQL-style changes rather than diffing declarative models the way Django or Alembic do.

How much of sqlite-utils 4.0 did Simon write with an AI model?

Simon Willison's 2026-07-05 companion post says the bulk of sqlite-utils 4.0rc2 was written with Claude Fable 5 over several days for about $149.25 in tokens. Willison reviewed and integrated the changes; the 4.0 final release incorporates additional fixes from a Claude Fable 5 code-review pass.

Simon Willison · 2026-07-07 · major

sqlite-utils 4.0 — schema migrations land in Simon Willison's SQLite toolkit

sqlite-utils 4.0 shipped on 2026-07-07, the first major version bump since November 2020. It adds a structured migrations system, nested transactions via db.atomic(), and compound foreign keys.

GitHub social preview for the simonw/sqlite-utils repository

First major sqlite-utils bump in five years brings migrations, nested transactions, and compound foreign keys.

Key specs

Version	4.0
GitHub stars	2,106

Quick facts

Maker	Simon Willison
Version	4.0
License	Apache-2.0
Language	Python
Install	pip install sqlite-utils
What's new	Migrations, nested transactions, compound foreign keys
Previous major	3.0 (November 2020)

What is it?

sqlite-utils 4.0 introduces a structured migrations system for evolving a project's SQLite schema over time. The 4.0 release is the first major bump since sqlite-utils 3.0 in November 2020 and adds sqlite_utils.Migrations plus a new sqlite-utils migrate CLI command that tracks applied migrations in a _sqlite_migrations table.

How does it work?

Migrations are ordinary Python files applied in sequence, wrapped by the new db.atomic() context manager that leans on SQLite Savepoints for real nested transactions. Compound (multi-column) foreign keys are now first-class in create, transform, and introspection paths, and upserts run through INSERT ... ON CONFLICT ... DO UPDATE SET with automatic primary-key detection.

Why does it matter?

sqlite-utils is one of the most-used third-party SQLite libraries in Python, and schema drift is the main reason teams outgrow it and reach for a heavier ORM. 4.0 keeps the library's programmatic, no-model-classes design while giving small SQLite projects a way to version their schema without adopting Django or Alembic.

Who is it for?

Python developers who script against SQLite and Datasette users

Frequently asked questions

What is new in sqlite-utils 4.0?: sqlite-utils 4.0 adds three headline features: a database migrations system (sqlite_utils.Migrations plus a sqlite-utils migrate CLI), nested transactions through the new db.atomic() context manager, and full compound (multi-column) foreign-key support. Upserts now use SQLite's ON CONFLICT syntax and CSV/TSV imports detect column types by default.
How do sqlite-utils migrations work?: sqlite-utils 4.0 migrations are Python files applied in order by the sqlite-utils migrate CLI. The library logs each applied migration in an internal _sqlite_migrations table so re-running the command only executes new ones. Each migration runs inside a db.atomic() block, so a failure rolls the whole step back cleanly.
Is sqlite-utils 4.0 backwards-compatible with 3.x scripts?: sqlite-utils 4.0 is a major version and includes breaking changes: db.query() now executes immediately and rejects non-row-returning statements (use db.execute() for writes and DDL), and column-name matching is case-insensitive. Simon Willison's release notes link to a dedicated upgrade guide covering the migration path from 3.x.
How does sqlite-utils compare to an ORM like Django or SQLAlchemy?: sqlite-utils 4.0 deliberately stays a thin toolkit around SQLite rather than a full ORM. It promotes programmatic table creation via table.transform() instead of model classes, so 4.0's migration system tracks raw SQL-style changes rather than diffing declarative models the way Django or Alembic do.
How much of sqlite-utils 4.0 did Simon write with an AI model?: Simon Willison's 2026-07-05 companion post says the bulk of sqlite-utils 4.0rc2 was written with Claude Fable 5 over several days for about $149.25 in tokens. Willison reviewed and integrated the changes; the 4.0 final release incorporates additional fixes from a Claude Fable 5 code-review pass.

Try it

pip install -U sqlite-utils