ValueObservation
ValueObservation tracks changes in the results of database requests, and notifies fresh values whenever the database changes.
For example:
let observation = ValueObservation.tracking { db in
try Player.fetchAll(db)
}
let cancellable = try observation.start(
in: dbQueue,
onError: { error in ... },
onChange: { (players: [Player]) in
print("Players have changed.")
})
-
Default is false. Set this property to true when the observation requires write access in order to fetch fresh values. Fetches are then wrapped inside a savepoint.
Don’t set this flag to true unless you really need it. A read/write observation is less efficient than a read-only observation.
-
Returns a shared value observation that shares a single underlying database observation for all subscriptions, and thus spares database resources.
For example:
let sharedObservation = ValueObservation .tracking { db in try Player.fetchAll(db) } .shared(in: dbQueue)
The sharing only applies if you start observing the database from the same
SharedValueObservation
instance:// NOT shared let cancellable1 = ValueObservation.tracking { db in ... }.shared(in: dbQueue).start(...) let cancellable2 = ValueObservation.tracking { db in ... }.shared(in: dbQueue).start(...) // Shared let sharedObservation = ValueObservation.tracking { db in ... }.shared(in: dbQueue) let cancellable1 = sharedObservation.start(...) let cancellable2 = sharedObservation.start(...)
By default, fresh values are dispatched asynchronously on the main queue. You can change this behavior by providing a scheduler. For example,
.immediate
notifies all values on the main queue as well, and the first one is immediately notified when the start() method is called:let sharedObservation = ValueObservation .tracking { db in try Player.fetchAll(db) } .shared( in: dbQueue, scheduling: .immediate) // <- let cancellable = try sharedObservation.start( onError: { error in ... }, onChange: { (players: [Player]) in print("fresh players: \(players)") }) // <- here "fresh players" is already printed.
Note that the
.immediate
scheduler requires that the observation is subscribed from the main thread. It raises a fatal error otherwise.A shared observation starts observing the database as soon as it is subscribed. You can choose if database observation should stop, or not, when its number of subscriptions drops down to zero, with the
extent
parameter. SeeSharedValueObservationExtent
for available options.
-
Starts the value observation in the provided database reader (such as a database queue or database pool).
The observation lasts until the returned cancellable is cancelled or deallocated.
For example:
let observation = ValueObservation.tracking { db in try Player.fetchAll(db) } let cancellable = try observation.start( in: dbQueue, onError: { error in ... }, onChange: { (players: [Player]) in print("fresh players: \(players)") })
By default, fresh values are dispatched asynchronously on the main queue. You can change this behavior by providing a scheduler. For example,
.immediate
notifies all values on the main queue as well, and the first one is immediately notified when the start() method is called:let cancellable = try observation.start( in: dbQueue, scheduling: .immediate, // <- onError: { error in ... }, onChange: { (players: [Player]) in print("fresh players: \(players)") }) // <- here "fresh players" is already printed.
Note that the
.immediate
scheduler requires that the observation is subscribed from the main thread. It raises a fatal error otherwise.
-
handleEvents(willStart:
willFetch: willTrackRegion: databaseDidChange: didReceiveValue: didFail: didCancel: ) Performs the specified closures when ValueObservation events occur.
-
Prints log messages for all ValueObservation events.
-
Creates an optimized
ValueObservation
that notifies the values returned by thefetch
function whenever a database transaction changes them.The optimization only kicks in when the observation is started from a
DatabasePool
: fresh values are fetched concurrently, and do not block database writes.Precondition
The fetch function must perform requests that fetch from a single and constant database region. The tracked region is made of tables, columns, and, when possible, rowids of individual rows. All changes that happen outside of this region do not impact the observation.For example:
// Tracks the full 'player' table let observation = ValueObservation.trackingConstantRegion { db -> [Player] in try Player.fetchAll(db) } // Tracks the row with id 42 in the 'player' table let observation = ValueObservation.trackingConstantRegion { db -> Player? in try Player.fetchOne(db, key: 42) } // Tracks the 'score' column in the 'player' table let observation = ValueObservation.trackingConstantRegion { db -> Int? in try Player.select(max(Column("score"))).fetchOne(db) } // Tracks both the 'player' and 'team' tables let observation = ValueObservation.trackingConstantRegion { db -> ([Team], [Player]) in let teams = try Team.fetchAll(db) let players = try Player.fetchAll(db) return (teams, players) }
When you want to observe a varying database region, make sure you use the
ValueObservation.tracking(_:)
method instead, or else some changes will not be notified.For example, consider those three observations below that depend on some user preference. They all track a varying region, and must use
ValueObservation.tracking(_:)
:// Does not always track the same row in the player table. let observation = ValueObservation.tracking { db -> Player? in let pref = try Preference.fetchOne(db) ?? .default return try Player.fetchOne(db, key: pref.favoritePlayerId) } // Only tracks the 'user' table if there are some blocked emails. let observation = ValueObservation.tracking { db -> [User] in let pref = try Preference.fetchOne(db) ?? .default let blockedEmails = pref.blockedEmails return try User.filter(blockedEmails.contains(Column("email"))).fetchAll(db) } // Sometimes tracks the 'food' table, and sometimes the 'beverage' table. let observation = ValueObservation.tracking { db -> Int in let pref = try Preference.fetchOne(db) ?? .default switch pref.selection { case .food: return try Food.fetchCount(db) case .beverage: return try Beverage.fetchCount(db) } }
-
Creates a
ValueObservation
that notifies the values returned by thefetch
function whenever a database transaction has an impact on the given regions.The tracked region is not automatically inferred from the requests performed in the
fetch
function.For example:
// Tracks the full database let observation = ValueObservation.tracking region: .fullDatabase, fetch: { db in ... }) // Tracks the full 'player' table let observation = ValueObservation.tracking region: Player.all(), fetch: { db in ... }) // Tracks the row with id 42 in the 'player' table let observation = ValueObservation.tracking region: Player.filter(id: 42), fetch: { db in ... }) // Tracks the 'score' column in the 'player' table let observation = ValueObservation.tracking region: Player.select(max(Column("score")), fetch: { db in ... }) // Tracks both the 'player' and 'team' tables let observation = ValueObservation.tracking region: Player.all(), Team.all(), fetch: { db in ... })
-
Creates a
ValueObservation
that notifies the values returned by thefetch
function whenever a database transaction has an impact on the given regions.The tracked region is not automatically inferred from the requests performed in the
fetch
function.For example:
// Tracks the full database let observation = ValueObservation.tracking regions: [.fullDatabase], fetch: { db in ... }) // Tracks the full 'player' table let observation = ValueObservation.tracking regions: [Player.all()], fetch: { db in ... }) // Tracks the row with id 42 in the 'player' table let observation = ValueObservation.tracking regions: [Player.filter(id: 42)], fetch: { db in ... }) // Tracks the 'score' column in the 'player' table let observation = ValueObservation.tracking regions: [Player.select(max(Column("score"))], fetch: { db in ... }) // Tracks both the 'player' and 'team' tables let observation = ValueObservation.tracking regions: [Player.all(), Team.all()], fetch: { db in ... })
-
Creates a
ValueObservation
that notifies the values returned by thefetch
function whenever a database transaction changes them.For example:
let observation = ValueObservation.tracking { db in try Player.fetchAll(db) } let cancellable = try observation.start( in: dbQueue, onError: { error in ... }, onChange: { (players: [Player]) in print("Players have changed") })
-
Returns a ValueObservation which notifies the results of calling the given transformation which each element notified by this value observation.
-
Returns a ValueObservation which only publishes elements that don’t match the previous element, as evaluated by a provided closure.
-
Returns a ValueObservation which filters out consecutive equal values.