GRDBCombine

A set of extensions for SQLite, GRDB.swift, and Combine


Latest release: version 0.7.0 (October 27, 2019) • Release Notes

Requirements: iOS 13.0+ / macOS 10.15+ / watchOS 6.0+ • Swift 5.1+ / Xcode 11.0+

Contact: Report bugs and ask questions in Github issues.


Usage

To connect to the database, please refer to GRDB, the database library that supports GRDBCombine.

Asynchronously read from the database This publisher reads a single value and delivers it. “`swift // AnyPublisher<[Player], Error> let players = dbQueue.readPublisher { db in try Player.fetchAll(db) } ”`
Asynchronously write in the database This publisher delivers a single value, after the database has been updated. “`swift // AnyPublisher let write = dbQueue.writePublisher { db in try Player(…).insert(db) } // AnyPublisher let newPlayerCount = dbQueue.writePublisher { db -> Int in try Player(…).insert(db) return try Player.fetchCount(db) } ”`
Observe changes in database values This publisher delivers fresh values whenever the database changes: “`swift // A publisher with output [Player] and failure Error let playersRequest = Player.all() let cancellable = ValueObservation .tracking(value: playersRequest.fetchAll) .publisher(in: dbQueue) // A publisher with output Int? and failure Error let maxScoreRequest = SQLRequest(sql: "SELECT MAX(score) FROM player”) let maxScorePublisher = ValueObservation .tracking(value: maxScoreRequest.fetchOne) .publisher(in: dbQueue) “`
Observe database transactions This publisher delivers database connections whenever a database transaction has impacted an observed region: ”`swift // A publisher with output Database and failure Error let playersRequest = Player.all() let playersChangePublisher = DatabaseRegionObservation .tracking(playersRequest) .publisher(in: dbQueue) // A publisher with output Database and failure Error let maxScoreRequest = SQLRequest(sql: “SELECT MAX(score) FROM player”) let maxScoreChangePublisher = DatabaseRegionObservation .tracking(maxScoreRequest) .publisher(in: dbQueue) “`

Documentation

Installation

The Swift Package Manager automates the distribution of Swift code. To use GRDBCombine with SPM, add a dependency to your Package.swift file:

let package = Package(
    dependencies: [
        .package(url: "https://github.com/groue/GRDBCombine.git", .exact("0.7.0"))
    ]
)

Asynchronous Database Access

GRDBCombine provide publishers that perform asynchronous database accesses.

DatabaseReader.readPublisher(receiveOn:value:)

This methods returns a publisher that completes after database values have been asynchronously fetched.

// AnyPublisher<[Player], Error>
let players = dbQueue.readPublisher { db in
    try Player.fetchAll(db)
}

Any attempt at modifying the database completes subscriptions with an error.

When you use a database queue or a database snapshot, the read has to wait for any eventual concurrent database access performed by this queue or snapshot to complete.

When you use a database pool, reads are generally non-blocking, unless the maximum number of concurrent reads has been reached. In this case, a read has to wait for another read to complete. That maximum number can be configured.

This publisher can be subscribed from any thread. A new database access starts on every subscription.

The fetched value is published on the main queue, unless you provide a specific scheduler to the receiveOn argument.

DatabaseWriter.writePublisher(receiveOn:updates:)

This method returns a publisher that completes after database updates have been succesfully executed inside a database transaction.

// AnyPublisher<Void, Error>
let write = dbQueue.writePublisher { db in
    try Player(...).insert(db)
}

// AnyPublisher<Int, Error>
let newPlayerCount = dbQueue.writePublisher { db -> Int in
    try Player(...).insert(db)
    return try Player.fetchCount(db)
}

This publisher can be subscribed from any thread. A new database access starts on every subscription.

It completes on the main queue, unless you provide a specific scheduler to the receiveOn argument.

When you use a database pool, and your app executes some database updates followed by some slow fetches, you may profit from optimized scheduling with writePublisher(receiveOn:updates:thenRead:). See below.

DatabaseWriter.writePublisher(receiveOn:updates:thenRead:)

This method returns a publisher that completes after database updates have been succesfully executed inside a database transaction, and values have been subsequently fetched:

// AnyPublisher<Int, Error>
let newPlayerCount = dbQueue.writePublisher(
    updates: { db in try Player(...).insert(db) }
    thenRead: { db, _ in try Player.fetchCount(db) })
}

It publishes exactly the same values as writePublisher(receiveOn:updates:):

// AnyPublisher<Int, Error>
let newPlayerCount = dbQueue.writePublisher { db -> Int in
    try Player(...).insert(db)
    return try Player.fetchCount(db)
}

The difference is that the last fetches are performed in the thenRead function. This function accepts two arguments: a readonly database connection, and the result of the updates function. This allows you to pass information from a function to the other (it is ignored in the sample code above).

When you use a database pool, this method applies a scheduling optimization: the thenRead function sees the database in the state left by the updates function, and yet does not block any concurrent writes. This can reduce database write contention. See Advanced DatabasePool for more information.

When you use a database queue, the results are guaranteed to be identical, but no scheduling optimization is applied.

This publisher can be subscribed from any thread. A new database access starts on every subscription.

It completes on the main queue, unless you provide a specific scheduler to the receiveOn argument.

Database Observation

GRDBCombine notifies changes that have been committed in the database. No insertion, update, or deletion in tracked tables is missed. This includes indirect changes triggered by foreign keys or SQL triggers.

To function correctly, GRDBCombine requires that a unique database connection is kept open during the whole duration of the observation.

:point_up: Note: some special changes are not notified: changes to SQLite system tables (such as sqlite_master), and changes to WITHOUT ROWID tables. See Data Change Notification Callbacks for more information.

To define which part of the database should be observed, you provide database requests. Requests can be expressed with GRDB’s query interface, as in Player.all(), or with SQL, as in SELECT * FROM player. Both would observe the full player database table. Observed requests can involve several database tables, and generally be as complex as you need them to be.

GRDBCombine publishers are based on GRDB’s ValueObservation and DatabaseRegionObservation. If your application needs change notifications that are not built in GRDBCombine, check the general Database Changes Observation chapter.

ValueObservation.publisher(in:)

GRDB’s ValueObservation notifies fresh values whenever the database changes. You can turn it into a Combine publisher:

let observation = ValueObservation.tracking { db in
    try Player.fetchAll(db)
}

// A publisher with output [Player] and failure Error
let publisher = observation.publisher(in: dbQueue)

This publisher always publishes an initial value, and waits for database changes before publishing updated values. It only completes when a database error happens.

All values are published on the main queue. Future GRDBCombine versions may lift this limitation.

By default, all values are published asynchronously:

// The default behavior
let cancellable = publisher.sink(
    receiveCompletion: { completion in ... },
    receiveValue: { (players: [Player]) in
        print("Fresh players: \(players)")
    })
// <- here "Fresh players" is not printed yet.

You can force a synchronous fetch of the initial value with the fetchOnSubscription() method. Subscription must then happen from the main queue, or you will get a fatal error:

// Synchronous initial fetch
let cancellable = publisher.fetchOnSubscription().sink(
    receiveCompletion: { completion in ... },
    receiveValue: { (players: [Player]) in
        print("Fresh players: \(players)")
    })
// <- here "Fresh players" has been printed.

:warning: ValueObservation and Data Consistency

When you compose ValueObservation publishers together with the combineLatest operator, you lose all guarantees of data consistency.

// CAUTION: DATA CONSISTENCY NOT GUARANTEED
let team = ValueObservation
    .tracking { db in try Team.fetchOne(db, key: 1) }
    .publisher(in: dbQueue)
let players = ValueObservation
    .tracking { db in try Player.filter(teamId: 1).fetchAll(db) }
    .publisher(in: dbQueue)
let publisher = team.combineLatest(players)

Instead, compose requests or value observations together before building a single publisher.

For example, fetch all requested values in a single observation:

// DATA CONSISTENCY GUARANTEED
// A publisher with output (Team?, [Player]) and failure Error
let publisher = ValueObservation
    .tracking { db -> (Team?, [Player]) in
        let team = try Team.fetchOne(db, key: 1)
        let players = Player.filter(teamId: 1).fetchAll(db)
        return (team, players)
    }
    .publisher(in: dbQueue)

Or use Associations:

// DATA CONSISTENCY GUARANTEED
struct TeamInfo: FetchableRecord, Decodable {
    var team: Team
    var players: [Player]
}
let request = Team
    .filter(key: 1)
    .including(all: Team.players)
    .asRequest(of: TeamInfo.self)

// A publisher with output TeamInfo? and failure Error
let publisher = ValueObservation
    .tracking(value: request.fetchOne)
    .publisher(in: dbQueue)

Or combine observations together:

// DATA CONSISTENCY GUARANTEED
let team = ValueObservation
    .tracking { db in try Team.fetchOne(db, key: 1) }
let players = ValueObservation
    .tracking { db in try Player.filter(teamId: 1).fetchAll(db) }
let observation = ValueObservation.combine(team, players)

// A publisher with output (Team?, [Player]) and failure Error
let publisher = observation.publisher(in: dbQueue)

See ValueObservation and Associations for more information.

DatabaseRegionObservation.publisher(in:)

GRDB’s DatabaseRegionObservation notifies all transactions that impact a tracked database region. You can turn it into a Combine publisher:

let request = Player.all()
let observation = DatabaseRegionObservation.tracking(request)

// A publisher with output Database and failure Error
let publisher = observation.publisher(in: dbQueue)

This publisher can be created and subscribed from any thread. It delivers database connections in a protected dispatch queue, serialized with all database updates. It only completes when a database error happens.

let request = Player.all()
let cancellable = DatabaseRegionObservation
    .tracking(request)
    .publisher(in: dbQueue)
    .sink(
        receiveCompletion: { completion in ... },
        receiveValue: { (db: Database) in
            print("Players have changed.")
        })

try dbQueue.write { db in
    try Player(name: "Arthur").insert(db)
    try Player(name: "Barbara").insert(db)
} 
// Prints "Players have changed."

try dbQueue.write { db in
    try Player.deleteAll(db)
}
// Prints "Players have changed."

See DatabaseRegionObservation for more information.