GRDB.swift: SQLite for Swift Apps, With Observation and Migrations Built In

What GRDB.swift Is For, and Who It Is Aimed At

GRDB.swift is a library that stores an application's permanent data in SQLite databases. The README frames it as a toolkit for SQLite databases "with a focus on application development," and it has been published under that description since 2015. The stated scope is app-facing: persistence and fetching methods on your model types, notifications when database values change, concurrency for multi-threaded apps including WAL databases, and schema migrations you ship alongside new app versions.

The intended user is a Swift developer building an app, not a server team and not a data engineer. The requirements listed in the README are Apple platform versions: iOS 13.0 or later, macOS 10.15 or later, tvOS 13.0 or later and watchOS 7.0 or later, with SQLite 3.20.0 or later, Swift 6.1 or later and Xcode 16.3 or later. That combination tells you the project is aimed at people shipping apps through Xcode, and the repository layout agrees: alongside Sources/ and Tests/ there are GRDB.xcodeproj, GRDB.xcworkspace and a GRDB.swift.podspec.

The problem it addresses is the gap between raw SQLite and an app's object model. SQLite's C API gives you prepared statements, rows and columns. An app wants a Player struct, a way to insert it, a query that returns an array of them, and a notification when one changes. GRDB.swift fills that gap while leaving the SQL visible when you want it. The README is explicit that the library does not hide SQLite: "Come with your SQL and SQLite skills, or learn new ones as you go."

Records, the Query Interface, and Raw SQL in the Same API

The core mechanism is a record type that conforms to Codable, FetchableRecord and PersistableRecord. Once a struct conforms, it gains persistence and fetching methods that take a database connection. The README's four-step example opens a DatabaseQueue with a file path, creates a table through db.create(table:), defines a Player struct with id, name and score, then writes and reads inside dbQueue.write and dbQueue.read closures.

The query interface is built on Swift key paths and column references. The README shows Player.find(db, id: "1") for a single record, Player.filter { $0.name == "Arthur" }.fetchOne(db) for an optional, and Player.order(\.score.desc).limit(10).fetchAll(db) for an array. A Columns enum maps CodingKeys to Column values so that queries can reference column names without string literals.

Underneath, the same connection exposes raw SQL. db.execute(sql:) runs a statement with positional arguments, and db.execute(literal:) uses SQL interpolation, which the README presents as the way to avoid SQL injection while still writing SQL by hand. Row.fetchCursor returns rows you advance through with next(), and typed helpers such as Int.fetchOne and String.fetchAll pull single values or arrays directly out of a query. The design choice here is deliberate: the Swift layer is a convenience, not a wall. If a query is easier to express in SQL than in key paths, nothing forces you through the Swift builder.

Installing GRDB.swift With Swift Package Manager

The README's installation section is the entry point, and the repository ships a Package.swift, so Swift Package Manager is the expected route for most apps. Add the package to your project's dependencies and let Xcode resolve it. The repository also carries a GRDB.swift.podspec for CocoaPods users and an Xcode project for direct integration.

The README's own example is the fastest way to confirm the package resolved correctly and the API is reachable. It opens a database at a file path and creates a table:

import GRDB

let dbQueue = try DatabaseQueue(path: "/path/to/database.sqlite")

try dbQueue.write { db in
    try db.create(table: "player") { t in
        t.primaryKey("id", .text)
        t.column("name", .text).notNull()
        t.column("score", .integer).notNull()
    }
}

If that compiles and runs without throwing, the connection and schema step work. The next step is a record type and a read, which is where the library starts paying for itself:

try dbQueue.write { db in
    try Player(id: "1", name: "Arthur", score: 100).insert(db)
}

try dbQueue.read { db in
    let bestPlayers = try Player
        .order(\.score.desc)
        .limit(10)
        .fetchAll(db)
}

What you should see is a row written inside the write closure and an array returned inside the read closure. The write and read closures are the concurrency boundary: GRDB serializes access through the queue rather than requiring you to manage a SQLite connection by hand.

Where GRDB.swift Gets in the Way

The library assumes you are building an Apple-platform app. The README states minimum versions of iOS 13.0, macOS 10.15, tvOS 13.0 and watchOS 7.0, plus SQLite 3.20.0 and Swift 6.1 with Xcode 16.3. A project pinned to an older Swift toolchain cannot take the current release. A server-side Swift project on Linux is not addressed by the stated requirements at all, and the repository's build machinery is Xcode-centric: the Makefile drives xcodebuild, and the smoke test targets are named for iOS frameworks and SQLCipher variants.

The second constraint is philosophical. GRDB.swift is not an ORM that hides SQL. If your team wants to define models and never see a SELECT statement, the query interface will feel like an extra layer rather than a replacement. The README's own framing, "Come with your SQL and SQLite skills, or learn new ones as you go," is a fair statement of the trade-off: you get power in exchange for knowing what is underneath.

The third is version churn. The README links a migration guide from GRDB 6 to GRDB 7, which means a major upgrade is a task with its own document, not a version bump. The release history shows v7.11.0 and v7.11.1 in June 2026 and v7.12.0 on November 1, 2026, so minor releases arrive regularly.

GRDB.swift Compared With SwiftData

The obvious alternative on Apple platforms is SwiftData, which is the framework Apple ships for persistence in SwiftUI apps. The difference in approach is who owns the schema and the store. SwiftData is an object graph and persistence framework tied to Apple's platform and its model macros; GRDB.swift is a SQLite toolkit where the schema is something you write, either through db.create(table:) or through raw CREATE TABLE statements, and the database file is a SQLite file you can open with any SQLite tool.

That matters in two situations. First, when you need queries that the abstraction cannot express, or when you want to inspect and repair data outside the app. Second, when you need database observation with the granularity the README describes, or when you need to control migrations explicitly as you ship new app versions. The README lists migrations and database observation as built-in tools, and the repository's Makefile passes SQLITE_ENABLE_FTS5 and SQLITE_ENABLE_PREUPDATE_HOOK as Swift flags, which indicates the build configures SQLite features rather than hiding them.

The cost of choosing GRDB.swift is that you own more of the design. You decide the schema, you write the migrations, and you decide when to drop to SQL. SwiftData asks less of you and gives you less control. Neither is universally better; the question is whether your app's data layer is a solved problem or a place where you need to look at the SQL.

Maintenance, Licensing and Upgrade Cost

The repository is not archived, and the last push was on 2026-11-02. The most recent release listed is v7.12.0 on 2026-11-01, following v7.11.1 on 2026-06-18 and v7.11.0 on 2026-06-01. The README points to a CHANGELOG, a migration guide from GRDB 6 to GRDB 7, and a CONTRIBUTING file, and it directs bug reports to GitHub issues and questions to GitHub discussions or the Swift forums. The project also publishes release announcements on Mastodon.

Licensing is MIT, per the LICENSE file in the repository root and the licence badge in the README. That is a permissive licence, but it is not legal advice and the obligations it places on redistribution should be confirmed with whoever handles licensing in your organisation.

Upgrade cost is the part worth budgeting for. The existence of a dedicated GRDB 6 to GRDB 7 migration guide signals that major versions are not drop-in. Minor releases have been frequent. If you pin a major version and read the CHANGELOG before moving, the work is bounded; if you track master, you are taking on that work continuously.

Editorial conclusion

Adopt GRDB.swift if you are building an iOS, macOS, tvOS or watchOS app that needs SQLite with migrations, concurrency handling and change notifications, and your team is comfortable reading SQL when the query interface is not enough. Do not adopt it if you want an ORM that hides the database, or if you are targeting platforms below the stated minimums. Before committing, verify that your deployment target meets the documented requirements, that your toolchain is Swift 6.1 or later, and that the observation features you plan to use behave as the documentation describes on your target platform.

Frequently asked questions

Official sources

1. groue/GRDB.swift on GitHub
2. Issues
3. License: MIT
4. README
5. Releases