Class
SQLiteConnection
final class SQLiteConnectionOverview
SQLiteConnection wraps a single sqlite3* handle and provides fully asynchronous, Swift-concurrency–friendly access to SQLite, as well as a multiplexed hook API that lets you register many Swift observers even though SQLite exposes only one slot per hook in C.
Storage
Choose how the underlying database is created when opening a connection via SQLiteConnection.Storage:
SQLiteConnection.Storage.memory– transient; lives only as long as the connection. Not shareable across processes (and, withSQLITE_OMIT_SHARED_CACHE, not across multiple connections in-process). Great for unit tests and scratch work.SQLiteConnection.Storage.file(path:)– persisted on disk; can be opened by multiple connections/processes subject to SQLite locking rules. Prefer absolute paths.
Observable Hooks
Each connection can fan out these SQLite hooks to multiple callbacks:
Update – row-level
INSERT/UPDATE/DELETEevents. SeeaddUpdateObserver(lifetime:_:).Commit – transaction about to commit; use
setCommitValidator(lifetime:_:)to veto commits oraddCommitObserver(lifetime:_:)for side-effect-only observation.Rollback – transaction was rolled back. See
addRollbackObserver(lifetime:_:).Authorizer – per-statement access control; use
setAuthorizerValidator(lifetime:_:)for access control oraddAuthorizerObserver(lifetime:_:)for side-effect-only observation.
Observer Registration Styles
Style |
API |
Lifetime |
Cleanup |
Notes |
|---|---|---|---|---|
Token-Based (Scoped) |
|
Until |
Auto on token dealloc |
Use for temporary observation. |
Token-Based (Pinned) |
|
Until |
|
Use for long-lived observation. |
Scoped |
|
Active only for closure duration |
Auto |
Handy for tests / temporary instrumentation. |
Threading
Registration is thread-safe. Callbacks run on SQLite’s internal thread, not your event loop or actor. Hop if needed:
let token = try await db.addUpdateObserver(lifetime: .pinned) { [weak self] event in
Task { await self?.myActor.handle(event) } // hop to actor
}Cleanup
Dropping a
SQLiteHookTokenwithSQLObserverLifetime/scopedlifetime auto-cancels on deallocation.Dropping a
SQLiteHookTokenwithSQLObserverLifetime/pinnedlifetime triggers a debug assertion but leaves the observer active.Call
cancel()to stop an observer early (works for both lifetimes).All observers are torn down automatically when the connection closes; later cancels are safe.
See
SQLiteObserverLifetimefor detailed lifetime behavior.
Topics
Instance Properties
let eventLoop: any EventLoopThe event loop on which operations on the connection execute.var isClosed: Boolfalseif the connection is valid,trueif not.let logger: LoggerThe logger used by the connection.
Instance Methods
func addAuthorizerObserver(lifetime: SQLiteObserverLifetime, SQLiteConnection.SQLiteAuthorizerObserver) async throws -> SQLiteHookTokenRegister an observer for the SQLite authorizer hook.func addCommitObserver(lifetime: SQLiteObserverLifetime, SQLiteConnection.SQLiteCommitObserver) async throws -> SQLiteHookTokenRegister a pure observer for SQLite commit events (cannot veto commits).func addRollbackObserver(lifetime: SQLiteObserverLifetime, SQLiteConnection.SQLiteRollbackHookCallback) async throws -> SQLiteHookTokenRegister an observer for the SQLite rollback hook.func addUpdateObserver(lifetime: SQLiteObserverLifetime, SQLiteConnection.SQLiteUpdateHookCallback) async throws -> SQLiteHookTokenRegister an observer for the SQLite update hook (row-level DML).func close()Close the connection and invalidate its handle.func install(customFunction:)Install the providedSQLiteCustomFunctionon the connection.func lastAutoincrementID()Returns the last value generated by auto-increment functionality (either the version implied byINTEGER PRIMARY KEYor that of the explicitAUTO_INCREMENTmodifier) on this database.func query(String, [SQLiteData], logger: Logger, (SQLiteRow) -> Void) -> EventLoopFuture<Void>Execute a query on the connection, calling the provided closure for each result row (if any).func setAuthorizerValidator(lifetime: SQLiteObserverLifetime, SQLiteConnection.SQLiteAuthorizerValidator) async throws -> SQLiteHookTokenSet the validator for the SQLite authorizer hook.func setCommitValidator(lifetime: SQLiteObserverLifetime, SQLiteConnection.SQLiteCommitValidator) async throws -> SQLiteHookTokenRegister a validator for SQLite commit events (can veto commits).func uninstall(customFunction:)Uninstall the providedSQLiteCustomFunctionfrom the connection.func withAuthorizerObserver<T>(SQLiteConnection.SQLiteAuthorizerObserver, body: () async throws -> T) async throws -> TExecute a block with a temporary authorizer observer.func withCommitObserver<T>(SQLiteConnection.SQLiteCommitObserver, body: () async throws -> T) async throws -> TExecute a block with a temporary commit observer.func withConnection(_:)Call the provided closure with a concreteSQLiteConnectioninstance.func withRollbackObserver<T>(SQLiteConnection.SQLiteRollbackHookCallback, body: () async throws -> T) async throws -> TExecute a block with a temporary rollback observer.func withUpdateObserver<T>(SQLiteConnection.SQLiteUpdateHookCallback, body: () async throws -> T) async throws -> TExecute a block with a temporary update observer.
Type Aliases
typealias SQLiteAuthorizerObserverThe type signature for authorizer observer callbacks.typealias SQLiteAuthorizerValidatorThe type signature for authorizer validator callbacks.typealias SQLiteCommitObserverThe type signature for commit observer callbacks (pure observation, cannot veto).typealias SQLiteCommitValidatorThe type signature for commit validator callbacks (can veto commits).typealias SQLiteRollbackHookCallbackThe type signature for rollback hook callbacks.typealias SQLiteUpdateHookCallbackThe type signature for update hook callbacks.
Type Methods
static func libraryVersion() -> Int32Return the version of the embedded libsqlite3 as a 32-bit integer value.static func libraryVersionString() -> StringReturn the version of the embedded libsqlite3 as a string.static open(storage:logger:)Open a new connection to an SQLite database.static open(storage:threadPool:logger:on:)Open a new connection to an SQLite database.
Enumerations
enum StorageThe possible storage types for an SQLite database.
Default Implementations
Relationships
Conforms To
SQLiteDatabaseSwift.SendableSwift.SendableMetatype