Database Observation
Observe database changes and transactions.
Overview
SQLite notifies its host application of changes performed to the database, as well of transaction commits and rollbacks.
GRDB puts this SQLite feature to some good use, and lets you observe the database in various ways:
ValueObservation: Get notified when database values change.DatabaseRegionObservation: Get notified when a transaction impacts a database region.afterNextTransaction(onCommit:onRollback:): Handle transactions commits or rollbacks, one by one.TransactionObserver: The low-level protocol that supports all database observation features.
Observing Database Values
struct ValueObservation<Reducer>ValueObservationtracks changes in the results of database requests, and notifies fresh values whenever the database changes.class SharedValueObservation<Element>A shared value observation spares database resources by sharing a single underlying
ValueObservationsubscription.struct AsyncValueObservation<Element>An asynchronous sequence of values observed by a
ValueObservation.func registerAccess(to: @autoclosure () -> some DatabaseRegionConvertible) throws Reports the database region to
ValueObservation.
Observing Database Transactions
struct DatabaseRegionObservationDatabaseRegionObservationtracks changes in a database region, and notifies impactful transactions.func afterNextTransaction(onCommit: @escaping (Database) -> Void, onRollback: @escaping (Database) -> Void) Registers closures to be executed after the next or current transaction completes.
Low-Level Transaction Observers
protocol TransactionObserverA type that tracks database changes and transactions performed in a database.
func add(transactionObserver: some TransactionObserver, extent: TransactionObservationExtent) Adds a transaction observer on the database connection, so that it gets notified of database changes and transactions.
func remove(transactionObserver: some TransactionObserver) Removes a transaction observer from the database connection.
func add(transactionObserver: some TransactionObserver, extent: Database.TransactionObservationExtent) Adds a transaction observer to the writer connection, so that it gets notified of database changes and transactions.
func remove(transactionObserver: some TransactionObserver) Removes a transaction observer from the writer connection.
enum TransactionObservationExtentThe extent of the observation performed by a
TransactionObserver.
Database Regions
struct DatabaseRegionAn observable region of the database.
protocol DatabaseRegionConvertibleA type that operates on a specific
DatabaseRegion.