Class

SQLiteConnection

Represents a single open connection to an SQLite database, either on disk or in memory.

final class SQLiteConnection

Overview

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, with SQLITE_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 / DELETE events. See addUpdateObserver(lifetime:_:).
Commit – transaction about to commit; use setCommitValidator(lifetime:_:) to veto commits or addCommitObserver(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 or addAuthorizerObserver(lifetime:_:) for side-effect-only observation.

Observer Registration Styles

Style	API	Lifetime	Cleanup	Notes
Token-Based (Scoped)	`add…Observer(lifetime: .scoped)`	Until `SQLiteHookToken` deallocated	Auto on token dealloc	Use for temporary observation.
Token-Based (Pinned)	`add…Observer(lifetime: .pinned)`	Until `SQLiteHookToken` canceled	`token.cancel()`	Use for long-lived observation.
Scoped	`with…Observer`	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 SQLiteHookToken with SQLObserverLifetime/scoped lifetime auto-cancels on deallocation.
Dropping a SQLiteHookToken with SQLObserverLifetime/pinned lifetime 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 SQLiteObserverLifetime for detailed lifetime behavior.

Topics

Instance Properties

eventLoop
The event loop on which operations on the connection execute.
isClosed
false if the connection is valid, true if not.
logger
The logger used by the connection.

Instance Methods

addAuthorizerObserver(lifetime:_:)
Register an observer for the SQLite authorizer hook.
addCommitObserver(lifetime:_:)
Register a pure observer for SQLite commit events (cannot veto commits).
addRollbackObserver(lifetime:_:)
Register an observer for the SQLite rollback hook.
addUpdateObserver(lifetime:_:)
Register an observer for the SQLite update hook (row-level DML).
close()
Close the connection and invalidate its handle.
install(customFunction:)
Install the provided SQLiteCustomFunction on the connection.
lastAutoincrementID()
Returns the last value generated by auto-increment functionality (either the version implied by INTEGER PRIMARY KEY or that of the explicit AUTO_INCREMENT modifier) on this database.
query(_:_:_:)
Concurrency-aware variant of query(_:_:_:)-etrj.
query(_:_:logger:_:)
Execute a query on the connection, calling the provided closure for each result row (if any).
setAuthorizerValidator(lifetime:_:)
Set the validator for the SQLite authorizer hook.
setCommitValidator(lifetime:_:)
Register a validator for SQLite commit events (can veto commits).
uninstall(customFunction:)
Uninstall the provided SQLiteCustomFunction from the connection.
withAuthorizerObserver(_:body:)
Execute a block with a temporary authorizer observer.
withCommitObserver(_:body:)
Execute a block with a temporary commit observer.
withConnection(_:)
Call the provided closure with a concrete SQLiteConnection instance.
withRollbackObserver(_:body:)
Execute a block with a temporary rollback observer.
withUpdateObserver(_:body:)
Execute a block with a temporary update observer.

Type Aliases

SQLiteConnection.SQLiteAuthorizerObserver
The type signature for authorizer observer callbacks.
SQLiteConnection.SQLiteAuthorizerValidator
The type signature for authorizer validator callbacks.
SQLiteConnection.SQLiteCommitObserver
The type signature for commit observer callbacks (pure observation, cannot veto).
SQLiteConnection.SQLiteCommitValidator
The type signature for commit validator callbacks (can veto commits).
SQLiteConnection.SQLiteRollbackHookCallback
The type signature for rollback hook callbacks.
SQLiteConnection.SQLiteUpdateHookCallback
The type signature for update hook callbacks.

Type Methods

libraryVersion()
Return the version of the embedded libsqlite3 as a 32-bit integer value.
libraryVersionString()
Return the version of the embedded libsqlite3 as a string.
open(storage:logger:)
Open a new connection to an SQLite database.
open(storage:threadPool:logger:on:)
Open a new connection to an SQLite database.