TransactionObserver

public protocol TransactionObserver : AnyObject

A transaction observer is notified of all changes and transactions committed or rollbacked on a database.

Adopting types must be a class.

  • Filters database changes that should be notified the the databaseDidChange(with:) method.

    Declaration

    Swift

    func observes(eventsOfKind eventKind: DatabaseEventKind) -> Bool
  • Notifies a database change (insert, update, or delete).

    The change is pending until the current transaction ends. See databaseWillCommit, databaseDidCommit and databaseDidRollback.

    This method is called in a protected dispatch queue, serialized will all database updates.

    The event is only valid for the duration of this method call. If you need to keep it longer, store a copy: event.copy()

    The observer has an opportunity to stop receiving further change events from the current transaction by calling the stopObservingDatabaseChangesUntilNextTransaction() method.

    Warning

    this method must not change the database.

    Declaration

    Swift

    func databaseDidChange(with event: DatabaseEvent)
  • databaseWillCommit() Default implementation

    When a transaction is about to be committed, the transaction observer has an opportunity to rollback pending changes by throwing an error.

    This method is called on the database queue.

    Warning

    this method must not change the database.

    Throws

    An eventual error that rollbacks pending changes.

    Default Implementation

    Default implementation does nothing

    Declaration

    Swift

    func databaseWillCommit() throws
  • Database changes have been committed.

    This method is called on the database queue. It can change the database.

    Declaration

    Swift

    func databaseDidCommit(_ db: Database)
  • Database changes have been rollbacked.

    This method is called on the database queue. It can change the database.

    Declaration

    Swift

    func databaseDidRollback(_ db: Database)
  • databaseWillChange(with:) Default implementation

    Notifies before a database change (insert, update, or delete) with change information (initial / final values for the row’s columns). (Called before databaseDidChangeWithEvent.)

    The change is pending until the end of the current transaction, and you always get a second chance to get basic event information in the databaseDidChangeWithEvent callback.

    This callback is mostly useful for calculating detailed change information for a row, and provides the initial / final values.

    This method is called in a protected dispatch queue, serialized will all database updates.

    The event is only valid for the duration of this method call. If you need to keep it longer, store a copy: event.copy()

    Warning

    this method must not change the database.

    Availability Info

    Requires SQLite 3.13.0 + Compiled with option SQLITE_ENABLE_PREUPDATE_HOOK

    As of OSX 10.11.5, and iOS 9.3.2, the built-in SQLite library does not have this enabled, so you’ll need to compile your own copy using GRDBCustomSQLite. See https://github.com/groue/GRDB.swift/blob/master/Documentation/CustomSQLiteBuilds.md

    The databaseDidChangeWithEvent callback is always available, and may provide most/all of what you need.

    Default Implementation

    Default implementation does nothing

  • After this method has been called, the databaseDidChange(with:) method won’t be called until the next transaction.

    For example:

    class PlayerObserver: TransactionObserver {
        var playerTableWasModified = false
    
        func observes(eventsOfKind eventKind: DatabaseEventKind) -> Bool {
            return eventKind.tableName == "player"
        }
    
        func databaseDidChange(with event: DatabaseEvent) {
            playerTableWasModified = true
    
            // It is pointless to keep on tracking further changes:
            stopObservingDatabaseChangesUntilNextTransaction()
        }
    }
    

    Precondition

    This method must be called from databaseDidChange(with:).

    Declaration

    Swift

    public func stopObservingDatabaseChangesUntilNextTransaction()