mirror of
https://github.com/groue/GRDB.swift
synced 2026-11-22 04:00:39 +00:00
Merge pull request #1864 from simolus3/development
Add `observe(statement:)` to `TransactionObserver`
This commit is contained in:
5 files changed
+238
-65
No files matched your search
@@ -297,6 +297,10 @@ class DatabaseObservationBroker {
|
||||
}
|
||||
}
|
||||
|
||||
/// Notifies that some changes were performed in the provided
|
||||
/// database region.
|
||||
///
|
||||
/// Support for the public ``Database/notifyChanges(in:)`` method.
|
||||
func notifyChanges(withEventsOfKind eventKinds: [DatabaseEventKind]) throws {
|
||||
// Support for stopObservingDatabaseChangesUntilNextTransaction()
|
||||
SchedulingWatchdog.current!.databaseObservationBroker = self
|
||||
@@ -334,65 +338,14 @@ class DatabaseObservationBroker {
|
||||
SchedulingWatchdog.current!.databaseObservationBroker = self
|
||||
|
||||
// Fill statementObservations with observations that are interested
|
||||
// in the kind of database events performed by the statement, as
|
||||
// reported by `sqlite3_set_authorizer`.
|
||||
//
|
||||
// in the kind of database events performed by the statement.
|
||||
// Those statementObservations will be notified of individual changes
|
||||
// in databaseWillChange() and databaseDidChange().
|
||||
let authorizerEventKinds = statement.authorizerEventKinds
|
||||
|
||||
switch authorizerEventKinds.count {
|
||||
case 0:
|
||||
// Statement has no effect on any database table.
|
||||
//
|
||||
// For example: PRAGMA foreign_keys = ON
|
||||
statementObservations = []
|
||||
case 1:
|
||||
// We'll execute a simple statement without any side effect.
|
||||
// Eventual database events will thus all have the same kind. All
|
||||
// detabase events can be notified to interested observations.
|
||||
//
|
||||
// For example, if one observes all deletions in the table T, then
|
||||
// all individual deletions of DELETE FROM T are notified:
|
||||
let eventKind = authorizerEventKinds[0]
|
||||
statementObservations = transactionObservations.compactMap { observation in
|
||||
guard observation.observes(eventsOfKind: eventKind) else {
|
||||
// observation is not interested
|
||||
return nil
|
||||
}
|
||||
|
||||
// Observation will be notified of all individual events
|
||||
return StatementObservation(
|
||||
transactionObservation: observation,
|
||||
trackingEvents: .all)
|
||||
}
|
||||
default:
|
||||
// We'll execute a complex statement with side effects performed by
|
||||
// an SQL trigger or a foreign key action. Eventual database events
|
||||
// may not all have the same kind: we need to filter them before
|
||||
// notifying interested observations.
|
||||
//
|
||||
// For example, if DELETE FROM T1 generates deletions in T1 and T2
|
||||
// by the mean of a foreign key action, then when one only observes
|
||||
// deletions in T1, one must not be notified of deletions in T2:
|
||||
statementObservations = transactionObservations.compactMap { observation in
|
||||
let observedEventKinds = authorizerEventKinds.filter(observation.observes)
|
||||
if observedEventKinds.isEmpty {
|
||||
// observation is not interested
|
||||
return nil
|
||||
}
|
||||
|
||||
// Observation will only be notified of individual events
|
||||
// it is interested into.
|
||||
return StatementObservation(
|
||||
transactionObservation: observation,
|
||||
trackingEvents: .matching(
|
||||
observedEventKinds: observedEventKinds,
|
||||
authorizerEventKinds: authorizerEventKinds))
|
||||
}
|
||||
statementObservations = transactionObservations.compactMap { observation in
|
||||
observation.statementObservation(for: statement)
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
transactionCompletion = .none
|
||||
}
|
||||
|
||||
@@ -798,16 +751,78 @@ class DatabaseObservationBroker {
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - DatabaseEventObservationStrategy
|
||||
|
||||
/// Controls which database changes are notified to a `TransactionObserver`.
|
||||
public struct DatabaseEventObservationStrategy: Sendable {
|
||||
/// A boolean value indicating whether a ``TransactionObserver`` focuses
|
||||
/// on database changes filtered by its
|
||||
/// ``TransactionObserver/observes(eventsOfKind:)`` method.
|
||||
///
|
||||
/// When this flag is true (the default), the only notified changes are
|
||||
/// those performed by `DELETE`, `INSERT` and `UPDATE` statements that
|
||||
/// are compiled and executed by GRDB. Other changes are not: changes
|
||||
/// performed by `SELECT` statements (through a database function),
|
||||
/// changes performed by statements compiled or executed with the SQLite
|
||||
/// C API.
|
||||
///
|
||||
/// Set this flag to false in order to be notified of all database events.
|
||||
///
|
||||
/// When this flag is false, an observer prevents the
|
||||
/// [truncate optimization](https://www.sqlite.org/lang_delete.html#the_truncate_optimization)
|
||||
/// from being applied on all database tables.
|
||||
public var requiresDatabaseEventKind: Bool
|
||||
|
||||
/// The default strategy for observing database change events.
|
||||
///
|
||||
/// In this default strategy, only the `DELETE`, `INSERT` and `UPDATE`
|
||||
/// statements that are compiled and executed by GRDB are observed.
|
||||
public static let `default` = DatabaseEventObservationStrategy(requiresDatabaseEventKind: true)
|
||||
}
|
||||
|
||||
// MARK: - TransactionObserver
|
||||
|
||||
public protocol TransactionObserver: AnyObject {
|
||||
|
||||
/// Controls which database changes should be notified to the observer.
|
||||
///
|
||||
/// The default value is ``DatabaseEventObservationStrategy/default``,
|
||||
/// which only detects changes performed by `DELETE`, `INSERT` and
|
||||
/// `UPDATE` statements that are compiled and executed by GRDB.
|
||||
///
|
||||
/// You can define a universal observer that observes changes performed
|
||||
/// by `SELECT` statements (through a database function), changes
|
||||
/// performed by statements compiled or executed with the SQLite C API,
|
||||
/// as below:
|
||||
///
|
||||
/// ```swift
|
||||
/// // An observer that observes all database changes.
|
||||
/// class UniversalObserver: TransactionObserver {
|
||||
/// var databaseEventObservationStrategy: DatabaseEventObservationStrategy {
|
||||
/// var strategy = DatabaseEventObservationStrategy.default
|
||||
/// // Don't filter on database event kind, so that we are
|
||||
/// // notified of changes performed through the SQLite C API:
|
||||
/// strategy.requiresDatabaseEventKind = false
|
||||
/// return strategy
|
||||
/// }
|
||||
///
|
||||
/// // You still have to provide an implementation for this method,
|
||||
/// // but it will never be called since `requiresDatabaseEventKind`
|
||||
/// // is false.
|
||||
/// func observes(eventsOfKind eventKind: DatabaseEventKind) -> Bool {
|
||||
/// false // ignored
|
||||
/// }
|
||||
///
|
||||
/// func databaseDidChange(with event: DatabaseEvent) {
|
||||
/// // Handle the change
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
var databaseEventObservationStrategy: DatabaseEventObservationStrategy { get }
|
||||
|
||||
/// Returns whether specific kinds of database changes should be notified
|
||||
/// to the observer.
|
||||
///
|
||||
/// When this method returns false, database events of this kind are not
|
||||
/// notified to the ``databaseDidChange(with:)`` method.
|
||||
///
|
||||
/// For example:
|
||||
///
|
||||
/// ```swift
|
||||
@@ -823,6 +838,11 @@ public protocol TransactionObserver: AnyObject {
|
||||
/// prevents the
|
||||
/// [truncate optimization](https://www.sqlite.org/lang_delete.html#the_truncate_optimization)
|
||||
/// from being applied on the observed tables.
|
||||
///
|
||||
/// - Note: This method is not called when the result of
|
||||
/// ``databaseEventObservationStrategy`` has the
|
||||
/// ``DatabaseEventObservationStrategy/requiresDatabaseEventKind``
|
||||
/// flag set to false.
|
||||
func observes(eventsOfKind eventKind: DatabaseEventKind) -> Bool
|
||||
|
||||
/// Called when the database was modified in some unspecified way.
|
||||
@@ -838,8 +858,12 @@ public protocol TransactionObserver: AnyObject {
|
||||
/// Called when the database is changed by an insert, update, or
|
||||
/// delete event.
|
||||
///
|
||||
/// The change is pending until the current transaction ends. See
|
||||
/// ``databaseWillCommit()-7mksu``, ``databaseDidCommit(_:)`` and
|
||||
/// Whether this method is called or not for any given change is
|
||||
/// controlled by ``databaseEventObservationStrategy`` and
|
||||
/// ``observes(eventsOfKind:)``.
|
||||
///
|
||||
/// The notified change is pending until the current transaction ends.
|
||||
/// See ``databaseWillCommit()-7mksu``, ``databaseDidCommit(_:)`` and
|
||||
/// ``databaseDidRollback(_:)``.
|
||||
///
|
||||
/// The observer has an opportunity to stop receiving further change events
|
||||
@@ -902,6 +926,11 @@ public protocol TransactionObserver: AnyObject {
|
||||
}
|
||||
|
||||
extension TransactionObserver {
|
||||
/// The default implementation does not observe statements.
|
||||
public var databaseEventObservationStrategy: DatabaseEventObservationStrategy {
|
||||
.default
|
||||
}
|
||||
|
||||
/// The default implementation does nothing.
|
||||
public func databaseWillCommit() throws { }
|
||||
|
||||
@@ -996,7 +1025,69 @@ final class TransactionObservation {
|
||||
}
|
||||
|
||||
func observes(eventsOfKind eventKind: DatabaseEventKind) -> Bool {
|
||||
observer?.observes(eventsOfKind: eventKind) ?? false
|
||||
guard let observer else {
|
||||
return false
|
||||
}
|
||||
return !observer.databaseEventObservationStrategy.requiresDatabaseEventKind || observer.observes(eventsOfKind: eventKind)
|
||||
}
|
||||
|
||||
func statementObservation(for statement: Statement) -> StatementObservation? {
|
||||
guard let observer else {
|
||||
return nil
|
||||
}
|
||||
|
||||
if !observer.databaseEventObservationStrategy.requiresDatabaseEventKind {
|
||||
return StatementObservation(
|
||||
transactionObservation: self,
|
||||
trackingEvents: .all)
|
||||
}
|
||||
|
||||
let authorizerEventKinds = statement.authorizerEventKinds
|
||||
|
||||
switch authorizerEventKinds.count {
|
||||
case 0:
|
||||
// Statement has no effect on any database table.
|
||||
//
|
||||
// For example: PRAGMA foreign_keys = ON
|
||||
return nil
|
||||
case 1:
|
||||
// We'll execute a simple statement without any side effect.
|
||||
// Eventual database events will thus all have the same kind. All
|
||||
// detabase events can be notified to interested observations.
|
||||
//
|
||||
// For example, if one observes all deletions in the table T, then
|
||||
// all individual deletions of DELETE FROM T are notified:
|
||||
guard observer.observes(eventsOfKind: authorizerEventKinds[0]) else {
|
||||
// observation is not interested
|
||||
return nil
|
||||
}
|
||||
|
||||
// Observation will be notified of all individual events
|
||||
return StatementObservation(
|
||||
transactionObservation: self,
|
||||
trackingEvents: .all)
|
||||
default:
|
||||
// We'll execute a complex statement with side effects performed by
|
||||
// an SQL trigger or a foreign key action. Eventual database events
|
||||
// may not all have the same kind: we need to filter them before
|
||||
// notifying interested observations.
|
||||
//
|
||||
// For example, if DELETE FROM T1 generates deletions in T1 and T2
|
||||
// by the mean of a foreign key action, then when one only observes
|
||||
// deletions in T1, one must not be notified of deletions in T2:
|
||||
let observedEventKinds = authorizerEventKinds.filter(observer.observes)
|
||||
if observedEventKinds.isEmpty {
|
||||
// observation is not interested
|
||||
return nil
|
||||
}
|
||||
// Observation will only be notified of individual events
|
||||
// it is interested into.
|
||||
return StatementObservation(
|
||||
transactionObservation: self,
|
||||
trackingEvents: .matching(
|
||||
observedEventKinds: observedEventKinds,
|
||||
authorizerEventKinds: authorizerEventKinds))
|
||||
}
|
||||
}
|
||||
|
||||
#if SQLITE_ENABLE_PREUPDATE_HOOK
|
||||
|
||||
@@ -79,7 +79,7 @@ let observation = DatabaseRegionObservation(
|
||||
`DatabaseRegionObservation` will not notify impactful transactions whenever the database is modified in an undetectable way:
|
||||
|
||||
- Changes performed by external database connections.
|
||||
- Changes performed by SQLite statements that are not compiled and executed by GRDB.
|
||||
- Changes performed by SQLite statements that are not a `DELETE`, `INSERT` or `UPDATE` statement compiled and executed by GRDB.
|
||||
- Changes to the database schema, changes to internal system tables such as `sqlite_master`.
|
||||
- Changes to [`WITHOUT ROWID`](https://www.sqlite.org/withoutrowid.html) tables.
|
||||
|
||||
|
||||
@@ -97,7 +97,7 @@ do {
|
||||
|
||||
**Transaction observers can choose the database changes they are interested in.**
|
||||
|
||||
The ``observes(eventsOfKind:)`` method filters events that are notified to ``databaseDidChange(with:)``. It is the most efficient and recommended change filtering technique, because it is only called once before a database query is executed, and can completely disable change tracking:
|
||||
By default, the ``observes(eventsOfKind:)`` method filters events that are notified to ``databaseDidChange(with:)``. It is the most efficient and recommended change filtering technique, because it is only called once before a database query is executed, and can completely disable change tracking:
|
||||
|
||||
```swift
|
||||
// Calls `observes(eventsOfKind:)` once.
|
||||
@@ -125,6 +125,8 @@ class PlayerObserver: TransactionObserver {
|
||||
|
||||
When the `observes(eventsOfKind:)` method returns false for all event kinds, the observer is still notified of transactions.
|
||||
|
||||
The filtering performed by ``observes(eventsOfKind:)`` makes a transaction observer unaware of changes performed by SQLite statements that are not a `DELETE`, `INSERT` or `UPDATE` statement compiled and executed by GRDB. You can lift this limitation with the ``TransactionObserver/databaseEventObservationStrategy``.
|
||||
|
||||
## Observation Extent
|
||||
|
||||
**You can specify how long an observer is notified of database changes and transactions.**
|
||||
@@ -232,7 +234,7 @@ The changes and transactions that are not automatically notified to transaction
|
||||
|
||||
- Read-only transactions.
|
||||
- Changes and transactions performed by external database connections.
|
||||
- Changes performed by SQLite statements that are not both compiled and executed through GRDB APIs.
|
||||
- Changes performed by SQLite statements that are not a `DELETE`, `INSERT` or `UPDATE` statement compiled and executed by GRDB (this limitation can be lifted, in your custom `TransactionObserver` type, with ``TransactionObserver/databaseEventObservationStrategy``).
|
||||
- Changes to the database schema, changes to internal system tables such as `sqlite_master`.
|
||||
- Changes to [`WITHOUT ROWID`](https://www.sqlite.org/withoutrowid.html) tables.
|
||||
- The deletion of duplicate rows triggered by [`ON CONFLICT REPLACE`](https://www.sqlite.org/lang_conflict.html) clauses (this last exception might change in a future release of SQLite).
|
||||
@@ -265,8 +267,10 @@ try dbQueue.write { db in
|
||||
|
||||
### Filtering Database Changes
|
||||
|
||||
- ``databaseEventObservationStrategy``
|
||||
- ``observes(eventsOfKind:)``
|
||||
- ``DatabaseEventKind``
|
||||
- ``DatabaseEventObservationStrategy``
|
||||
|
||||
### Handling Database Changes
|
||||
|
||||
|
||||
@@ -228,7 +228,7 @@ This ``tracking(region:_:fetch:)`` method lets you entirely separate the **obser
|
||||
`ValueObservation` will not fetch and notify a fresh value whenever the database is modified in an undetectable way:
|
||||
|
||||
- Changes performed by external database connections.
|
||||
- Changes performed by SQLite statements that are not compiled and executed by GRDB.
|
||||
- Changes performed by SQLite statements that are not a `DELETE`, `INSERT` or `UPDATE` statement compiled and executed by GRDB.
|
||||
- Changes to the database schema, changes to internal system tables such as `sqlite_master`.
|
||||
- Changes to [`WITHOUT ROWID`](https://www.sqlite.org/withoutrowid.html) tables.
|
||||
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
import XCTest
|
||||
import GRDB
|
||||
import SQLite3
|
||||
|
||||
private class EverythingObserver: TransactionObserver {
|
||||
var changedTables = Set<String>()
|
||||
|
||||
var databaseEventObservationStrategy: DatabaseEventObservationStrategy {
|
||||
var strategy = DatabaseEventObservationStrategy.default
|
||||
strategy.requiresDatabaseEventKind = false
|
||||
return strategy
|
||||
}
|
||||
|
||||
func databaseDidChange(with event: GRDB.DatabaseEvent) {
|
||||
changedTables.insert(event.tableName)
|
||||
}
|
||||
|
||||
func observes(eventsOfKind eventKind: DatabaseEventKind) -> Bool {
|
||||
fatalError("Should not be called since requiresDatabaseEventKind is false")
|
||||
}
|
||||
|
||||
func databaseDidCommit(_ db: GRDB.Database) {}
|
||||
|
||||
func databaseDidRollback(_ db: GRDB.Database) {}
|
||||
}
|
||||
|
||||
private struct SendablePtr: @unchecked Sendable {
|
||||
let ptr: OpaquePointer
|
||||
}
|
||||
|
||||
class DatabaseEventObservationStrategyTest: GRDBTestCase {
|
||||
func testIndirectWrite() throws {
|
||||
var config = Configuration()
|
||||
config.prepareDatabase{ database in
|
||||
// Replicate what a native SQLite extension might do, running statements in a user-defined functions
|
||||
let ptr = SendablePtr(ptr: database.sqliteConnection!)
|
||||
|
||||
database.add(function: DatabaseFunction("custom_clear_function", function: { values in
|
||||
var err: UnsafeMutablePointer<CChar>?
|
||||
let rc = sqlite3_exec(ptr.ptr, "DELETE FROM foo", nil, nil, &err)
|
||||
if rc != 0 {
|
||||
let msg = String(cString: err!)
|
||||
fatalError(msg)
|
||||
}
|
||||
return rc
|
||||
}))
|
||||
}
|
||||
let db = try makeDatabaseQueue(configuration: config)
|
||||
try db.writeWithoutTransaction { db in
|
||||
try db.execute(sql: "CREATE TABLE foo (bar TEXT)")
|
||||
try db.execute(sql: "INSERT INTO foo DEFAULT VALUES")
|
||||
}
|
||||
|
||||
let observer = EverythingObserver()
|
||||
db.add(transactionObserver: observer)
|
||||
try db.writeWithoutTransaction { db in
|
||||
try db.execute(sql: "SELECT custom_clear_function()")
|
||||
}
|
||||
|
||||
XCTAssert(observer.changedTables == ["foo"])
|
||||
}
|
||||
|
||||
func testDisablesTruncateOptimization() throws {
|
||||
let db = try makeDatabaseQueue()
|
||||
try db.writeWithoutTransaction { db in
|
||||
try db.execute(sql: "CREATE TABLE foo (bar TEXT)")
|
||||
try db.execute(sql: "INSERT INTO foo DEFAULT VALUES")
|
||||
}
|
||||
|
||||
let observer = EverythingObserver()
|
||||
db.add(transactionObserver: observer)
|
||||
try db.writeWithoutTransaction { db in
|
||||
try db.execute(sql: "DELETE FROM foo")
|
||||
}
|
||||
|
||||
XCTAssert(observer.changedTables == ["foo"])
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user