SQLite.swift: typed SQL expressions over SQLite3, and the prepare(_:) iteration that can crash your app
A type-safe, Swift-language layer over SQLite3.
At a glance
- What is it?
- SQLite.swift is an MIT-licensed Swift layer over SQLite3 that builds tables and queries from typed, optional-aware expressions while still exposing raw prepared statements. This piece covers how its expression builder maps Swift types to columns, the force-try behavior in row iteration, its WAL and SQLCipher entry points, the four install routes, and what Linux and SwiftUI users need to know.
- Who is it for?
- SQLite.swift fits Swift developers who want SQLite tables and queries checked by the compiler through typed expressions, with raw SQL still available on the same connection, and who are comfortable on a 0.x library whose latest release, 0.17.0, shipped in October 2026.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Swift, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- stephencelis/SQLite.swift10,186 ★ · -3
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| stephencelis/SQLite.swift | 10.2k | 10.2k |
-3 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Typed expressions turn Swift optionals into NULL and NOT NULL columns
The core of SQLite.swift is an expression builder in which every column is a typed Swift value. You declare a Table and a set of expressions, and the type parameter decides both the SQLite type and nullability:
import SQLite
// Wrap everything in a do...catch to handle errors
do {
let db = try Connection("path/to/db.sqlite3")
let users = Table("users")
let id = SQLite.Expression<Int64>("id")
let name = SQLite.Expression<String?>("name")
let email = SQLite.Expression<String>("email")
try db.run(users.create { t in
t.column(id, primaryKey: true)
t.column(name)
t.column(email, unique: true)
})
// CREATE TABLE "users" (
// "id" INTEGER PRIMARY KEY NOT NULL,
// "name" TEXT,
// "email" TEXT NOT NULL UNIQUE
// )
Read the generated SQL in the comment. Int64 becomes INTEGER, String becomes TEXT, and the optional String? for name is the only column without NOT NULL. That is what optional-aware means here: the nullability you write in Swift ends up in the schema, and data read back carries the same types, so code reading name has to deal with nil while code reading email does not. Queries built on these expressions are chainable and lazy, executing only when results are requested. The project's claim is compile-time confidence in both SQL syntax and intent, which in practice means a misspelled column variable or a type mismatch fails to compile instead of failing at run time.
Write SQLite.Expression, not Expression, in any file that also imports SwiftUI
The example above spells out SQLite.Expression on every column, and that is deliberate. SwiftUI defines its own Expression type, and a file that imports both SwiftUI and SQLite cannot resolve the bare name to one of them. The project's guidance is to always write SQLite.Expression to avoid that conflict.
The consequence shows up in older tutorials and code samples that use the short form Expression<Int64>. Pasted into a SwiftUI view model or any file importing SwiftUI, those samples stop compiling because the name is ambiguous, even though nothing about your database code is wrong. If you are migrating an older codebase, a project-wide replacement to the qualified name is the simplest fix, and it keeps the code compiling whether or not SwiftUI is imported in a given file.
This is a naming collision, not a bug in either library, so it will not go away with an upgrade. Treat the qualified spelling as the normal way to write column expressions with SQLite.swift.
Iterating prepare(_:) force-tries each step and crashes on SQLITE_BUSY
The most serious caveat in SQLite.swift sits in the row loop. Iterating the sequence returned by prepare(_:) force-tries every step. If SQLite reports an error partway through the results, the app crashes instead of throwing. The examples given are SQLITE_BUSY, raised while another connection holds a lock, and I/O errors.
That turns ordinary database conditions into crashes. An app that opens more than one connection to the same file, or that runs a write on a background task while the UI reads, can hit a lock during a read loop, and the do...catch around your code will not catch it because nothing is thrown.
The fix is a different reading API. prepareRowIterator(_:) returns rows through failable iteration, so errors surface as Swift errors you can handle, retry or report. The Failable iteration section of Documentation/Index.md covers it. If you are adopting SQLite.swift today, use prepareRowIterator(_:) for any read that can run concurrently with writes, and audit existing for row in try db.prepare(...) loops before shipping.
Raw SQL on the same Connection, with change counters and row IDs
The typed builder is optional. SQLite.swift also works as a thin, Swift-friendly wrapper over SQLite's C API, so you can prepare a statement from a SQL string and run it repeatedly with bound parameters:
let stmt = try db.prepare("INSERT INTO users (email) VALUES (?)")
for email in ["[email protected]", "[email protected]"] {
try stmt.run(email)
}After writes, the Connection exposes three properties: totalChanges, changes and lastInsertRowid. In the upstream example, after these two inserts on top of an earlier row, they read 3, 1 and 3, so you can confirm how many rows a statement touched and which ID the last insert received without another query.
Rows read through raw SQL come back positionally, as row[0] and row[1], and the values are optionals, as in Optional(2) and Optional("[email protected]"). You give up the typed column access of the builder in exchange for writing exactly the SQL you want. For a single value, db.scalar accepts a SELECT string directly. The same force-try warning applies to raw SELECT loops built on prepare.
WAL, full-text search and SQLCipher each have their own switch
Several SQLite features have first-class entry points instead of requiring raw PRAGMA statements. Write-ahead logging can be turned on when the connection opens, with Connection(_, journalMode: .wal), or later through enableWAL(), and walCheckpoint(...) triggers checkpoints explicitly. Journaling configuration in general is exposed through the same API family.
Full-text search is supported, with its own section in Documentation/Index.md, and so is querying the schema for migrations. For versioned migrations on top of that, SQLiteMigrationManager.swift is the project named as building on SQLite.swift, inspired by FMDBMigrationManager.
Encryption comes through SQLCipher, and the support is stated as available via Swift Package Manager. The consequence for teams on CocoaPods, Carthage or the manual Xcode sub-project route is that encrypted databases are tied to the SwiftPM path. If encryption at rest is a requirement, settle on SwiftPM before writing code that assumes it, rather than discovering the dependency route has to change late in a project.
SwiftPM, CocoaPods, Carthage or a dragged-in Xcode project
SQLite.swift can be added four ways. With Swift Package Manager, add the dependency to Package.swift:
dependencies: [
.package(url: "https://github.com/stephencelis/SQLite.swift.git", from: "0.17.0")
]Then build:
$ swift buildThe repository's Tests/SPM folder contains a small demo project that uses SPM, which is a quick way to see a working manifest. A SQLite.swift.podspec at the repository root serves CocoaPods, and the project is marked Carthage compatible.
The manual route drags SQLite.xcodeproj into your own project, after you submodule, clone or download it, then adds the matching SQLite.framework under Linked Frameworks and Libraries in the target's General tab. That alone is not enough to run on a physical device: you must also add SQLite.framework under Embedded Binaries in the same tab. These extra steps are what it takes to install the app on an actual device, so a setup that skips them is incomplete the moment you move off your Mac.
Linux runs with limitations, and the tooling assumes Xcode
SQLite.swift works on Linux, with some limitations recorded in Documentation/Linux.md. Read that file before committing a server-side Swift project to the library, because the Apple-platform experience is the reference the rest of the project is built around.
The Makefile shows that bias. Its targets drive xcodebuild with the SQLite Mac scheme by default, or SQLite iOS against an iPhone 17 simulator on iOS 26.5. make lint downloads SwiftLint 0.63.1 and runs it with --strict, make test pipes output through xcbeautify 3.2.1, and make repl builds the framework into a temporary derived-data path and opens a Swift REPL linked against it. xcbeautify has a Linux x86_64 download path in the Makefile, but the build and test targets themselves call xcodebuild. For interactive exploration, the repository also ships an Xcode playground, SQLite.playground.
The project carries a Swift 6 compatible badge. Releases arrive at a steady pace: 0.15.5 on 22 January 2026, 0.16.0 on 8 March 2026 and 0.17.0 on 20 October 2026, with the last push on 25 October 2026. CHANGELOG.md records what changed between them, and pre-1.0 version numbers mean minor bumps deserve a read before upgrading. If SQLite.swift does not fit, the alternatives it names itself are GRDB, SQLiteDB and FMDB.
Editorial conclusion
SQLite.swift fits Swift developers who want SQLite tables and queries checked by the compiler through typed expressions, with raw SQL still available on the same connection, and who are comfortable on a 0.x library whose latest release, 0.17.0, shipped in October 2026. It is a weaker fit for code that reads rows with prepare(_:) in places where SQLITE_BUSY or I/O errors can occur, unless you switch those reads to prepareRowIterator(_:), and for Linux targets until you have read Documentation/Linux.md. Before adopting it, decide between SwiftPM, CocoaPods, Carthage or the manual Xcode route, and if you need encryption, plan on SwiftPM, since SQLCipher support comes through that path.
Frequently asked questions
What is a good database for Swift, and where does SQLite.swift fit?
SQLite.swift is an MIT-licensed, type-safe Swift layer over SQLite3 with a chainable query builder, full-text search, WAL configuration and SQLCipher support via SwiftPM. The project itself names GRDB, SQLiteDB and FMDB as alternatives.
Why does my SQLite.swift app crash with SQLITE_BUSY while reading rows?
Iterating the sequence returned by prepare(_:) force-tries each step, so an error such as SQLITE_BUSY or an I/O error crashes the app instead of throwing. Read rows with prepareRowIterator(_:) to get errors you can catch.
Why should I write SQLite.Expression instead of Expression in SQLite.swift?
SwiftUI has its own Expression type, so the bare name conflicts in files that import SwiftUI. Writing SQLite.Expression<Int64>("id") avoids the ambiguity.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/stephencelis-sqlite-swift)Star history chart for your README
[](https://hysenlabs.com/projects/stephencelis-sqlite-swift)Was this useful?