Merge branch 'development'

Author: groue

.github/workflows/CI.yml

@@ -57,7 +57,7 @@ jobs:
             name: "macOS 10.15, Xcode 12.4, Swift 5.3"
             shell: "/bin/zsh {0}"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: ${{ matrix.name }}
         run: make test_framework_GRDBOSX_maxSwift
   iOS:
@@ -77,7 +77,7 @@ jobs:
             name: "macOS 10.15, Xcode 12.4, Swift 5.3"
             shell: "/bin/zsh {0}"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: ${{ matrix.name }}
         run: make test_framework_GRDBiOS_maxTarget_maxSwift
   SPM:
@@ -93,7 +93,7 @@ jobs:
             name: "macOS 12, Xcode 13.3.1, Swift 5.6"
             shell: "/bin/zsh {0}"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: ${{ matrix.name }}
         run: make test_SPM test_install_SPM
   SQLCipher3:
@@ -109,7 +109,7 @@ jobs:
             name: "macOS 12, Xcode 13.3.1, Swift 5.6"
             shell: "/bin/zsh {0}"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: ${{ matrix.name }}
         run: make test_framework_SQLCipher3Encrypted
   SQLCipher4:
@@ -129,7 +129,7 @@ jobs:
             name: "macOS 10.15, Xcode 12.4, Swift 5.3"
             shell: "/bin/zsh {0}"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: ${{ matrix.name }}
         run: make test_framework_SQLCipher4Encrypted
   CustomSQLite:
@@ -149,7 +149,7 @@ jobs:
             name: "macOS 10.15, Xcode 12.4, Swift 5.3"
             shell: "/bin/zsh {0}"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: ${{ matrix.name }}
         run: make test_framework_GRDBCustomSQLiteOSX
   XCFramework:
@@ -165,7 +165,7 @@ jobs:
             name: "macOS 12, Xcode 13.3.1, Swift 5.6"
             shell: "/bin/zsh {0}"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: ${{ matrix.name }}
         run: make test_archive_GRDBOSX_xcframework
 

CHANGELOG.md

@@ -7,6 +7,7 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 
 #### 5.x Releases
 
+- `5.26.x` Releases - [5.26.0](#5260)
 - `5.25.x` Releases - [5.25.0](#5250)
 - `5.24.x` Releases - [5.24.0](#5240) | [5.24.1](#5241)
 - `5.23.x` Releases - [5.23.0](#5230)
@@ -92,6 +93,14 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 
 ---
 
+## 5.26.0
+
+Released July 9, 2022 • [diff](https://github.com/groue/GRDB.swift/compare/v5.25.0...v5.26.0)
+
+- **New**: [#1248](https://github.com/groue/GRDB.swift/pull/1248) by [@groue](https://github.com/groue): Avoid double notification of the initial value for ValueObservation on DatabasePool
+- **New**: [#1253](https://github.com/groue/GRDB.swift/pull/1253) by [@george-signal](https://github.com/george-signal): Make memory management optional
+- **Fixed**: DatabasePool no longer prevents database reads when UIKit posts `UIApplication.didReceiveMemoryWarningNotification` (see [#1253](https://github.com/groue/GRDB.swift/pull/1253) for more information).
+
 ## 5.25.0
 
 Released June 11, 2022 • [diff](https://github.com/groue/GRDB.swift/compare/v5.24.1...v5.25.0)

Documentation/AssociationsBasics.md

@@ -1510,7 +1510,7 @@ let sortedAuthor = Book.author.order(Column("name"))
 let request = Book.including(required: sortedAuthor)
 ```
 
-When you sort both the base record on the associated record, the request is sorted on the base record first, and on the associated record next:
+When you sort both the base record and the associated record, the request is sorted on the base record first, and on the associated record next:
 
 ```swift
 // SELECT book.*, person.*

Documentation/FullTextSearch.md

@@ -304,7 +304,7 @@ let pattern = FTS3Pattern(matchingAnyTokenIn: "")  // nil
 let pattern = FTS3Pattern(matchingAnyTokenIn: "*") // nil
 ```
 
-FTS3Pattern are regular [values](../README.md#values). You can use them as query [arguments](http://groue.github.io/GRDB.swift/docs/5.25/Structs/StatementArguments.html):
+FTS3Pattern are regular [values](../README.md#values). You can use them as query [arguments](http://groue.github.io/GRDB.swift/docs/5.26/Structs/StatementArguments.html):
 
 ```swift
 let documents = try Document.fetchAll(db,
@@ -587,7 +587,7 @@ let pattern = FTS5Pattern(matchingAnyTokenIn: "")  // nil
 let pattern = FTS5Pattern(matchingAnyTokenIn: "*") // nil
 ```
 
-FTS5Pattern are regular [values](../README.md#values). You can use them as query [arguments](http://groue.github.io/GRDB.swift/docs/5.25/Structs/StatementArguments.html):
+FTS5Pattern are regular [values](../README.md#values). You can use them as query [arguments](http://groue.github.io/GRDB.swift/docs/5.26/Structs/StatementArguments.html):
 
 ```swift
 let documents = try Document.fetchAll(db,

Documentation/Migrations.md

@@ -77,7 +77,7 @@ try dbQueue.read { db in
 }
 ```
 
-See the [DatabaseMigrator reference](http://groue.github.io/GRDB.swift/docs/5.25/Structs/DatabaseMigrator.html) for more migrator methods.
+See the [DatabaseMigrator reference](http://groue.github.io/GRDB.swift/docs/5.26/Structs/DatabaseMigrator.html) for more migrator methods.
 
 
 ## The `eraseDatabaseOnSchemaChange` Option

GRDB.swift.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name     = 'GRDB.swift'
-  s.version  = '5.25.0'
+  s.version  = '5.26.0'
 
   s.license  = { :type => 'MIT', :file => 'LICENSE' }
   s.summary  = 'A toolkit for SQLite databases, with a focus on application development.'

GRDB.xcodeproj/project.pbxproj

@@ -733,6 +733,10 @@
 		56B14E831D4DAE54000BF4A3 /* RowFromDictionaryLiteralTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 56B14E7E1D4DAE54000BF4A3 /* RowFromDictionaryLiteralTests.swift */; };
 		56B6EF56208CB4E3002F0ACB /* ColumnExpressionTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 56B6EF55208CB4E3002F0ACB /* ColumnExpressionTests.swift */; };
 		56B6EF57208CB4E3002F0ACB /* ColumnExpressionTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 56B6EF55208CB4E3002F0ACB /* ColumnExpressionTests.swift */; };
+		56B7EE832863781300C0525F /* WALSnapshot.swift in Sources */ = {isa = PBXBuildFile; fileRef = 56B7EE822863781300C0525F /* WALSnapshot.swift */; };
+		56B7EE842863781300C0525F /* WALSnapshot.swift in Sources */ = {isa = PBXBuildFile; fileRef = 56B7EE822863781300C0525F /* WALSnapshot.swift */; };
+		56B7EE852863781300C0525F /* WALSnapshot.swift in Sources */ = {isa = PBXBuildFile; fileRef = 56B7EE822863781300C0525F /* WALSnapshot.swift */; };
+		56B7EE862863781300C0525F /* WALSnapshot.swift in Sources */ = {isa = PBXBuildFile; fileRef = 56B7EE822863781300C0525F /* WALSnapshot.swift */; };
 		56B7F42A1BE14A1900E39BBF /* CGFloatTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 56B7F4291BE14A1900E39BBF /* CGFloatTests.swift */; };
 		56B7F43A1BEB42D500E39BBF /* Migration.swift in Sources */ = {isa = PBXBuildFile; fileRef = 56B7F4391BEB42D500E39BBF /* Migration.swift */; };
 		56B7F43B1BEB42D500E39BBF /* Migration.swift in Sources */ = {isa = PBXBuildFile; fileRef = 56B7F4391BEB42D500E39BBF /* Migration.swift */; };
@@ -1595,6 +1599,7 @@
 		56B021C81D8C0D3900B239BB /* MutablePersistableRecordPersistenceConflictPolicyTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = MutablePersistableRecordPersistenceConflictPolicyTests.swift; sourceTree = "<group>"; };
 		56B14E7E1D4DAE54000BF4A3 /* RowFromDictionaryLiteralTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = RowFromDictionaryLiteralTests.swift; sourceTree = "<group>"; };
 		56B6EF55208CB4E3002F0ACB /* ColumnExpressionTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ColumnExpressionTests.swift; sourceTree = "<group>"; };
+		56B7EE822863781300C0525F /* WALSnapshot.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WALSnapshot.swift; sourceTree = "<group>"; };
 		56B7F4291BE14A1900E39BBF /* CGFloatTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = CGFloatTests.swift; sourceTree = "<group>"; };
 		56B7F4391BEB42D500E39BBF /* Migration.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Migration.swift; sourceTree = "<group>"; };
 		56B86E72220FF4E000524C16 /* SQLLiteralTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = SQLLiteralTests.swift; sourceTree = "<group>"; };
@@ -2375,8 +2380,9 @@
 				56A238781B9C75030082EB20 /* Statement.swift */,
 				566B912A1FA4D0CC0012D5B0 /* StatementAuthorizer.swift */,
 				560D923F1C672C3E00F4F92B /* StatementColumnConvertible.swift */,
-				5605F1471C672E4000235C62 /* Support */,
 				566B91321FA4D3810012D5B0 /* TransactionObserver.swift */,
+				56B7EE822863781300C0525F /* WALSnapshot.swift */,
+				5605F1471C672E4000235C62 /* Support */,
 			);
 			path = Core;
 			sourceTree = "<group>";
@@ -2976,6 +2982,7 @@
 				565490D81D5AE252005622CB /* DatabaseMigrator.swift in Sources */,
 				5656A8AF2295BFD7001FF3FF /* TableRecord+Association.swift in Sources */,
 				565490C21D5AE236005622CB /* Row.swift in Sources */,
+				56B7EE852863781300C0525F /* WALSnapshot.swift in Sources */,
 				565490C71D5AE236005622CB /* StatementColumnConvertible.swift in Sources */,
 				565490D91D5AE252005622CB /* Migration.swift in Sources */,
 				56CEB5001EAA2F4D00BFAF62 /* FTS3.swift in Sources */,
@@ -3145,6 +3152,7 @@
 				5671FC231DA3CAC9003BF4FF /* FTS3TokenizerDescriptor.swift in Sources */,
 				56D51D031EA789FA0074638A /* FetchableRecord+TableRecord.swift in Sources */,
 				56DDDDF5242F87C60025E381 /* ValueObservationScheduler.swift in Sources */,
+				56B7EE842863781300C0525F /* WALSnapshot.swift in Sources */,
 				560D924C1C672C4B00F4F92B /* TableRecord.swift in Sources */,
 				56A2FA3B24424F4700E97D23 /* Export.swift in Sources */,
 				569BBA4F229170F900478429 /* Inflections+English.swift in Sources */,
@@ -3753,6 +3761,7 @@
 				AAA4DCA5230F1E0600C74B15 /* FTS3TokenizerDescriptor.swift in Sources */,
 				AAA4DCA6230F1E0600C74B15 /* FetchableRecord+TableRecord.swift in Sources */,
 				56DDDDF7242F87C70025E381 /* ValueObservationScheduler.swift in Sources */,
+				56B7EE862863781300C0525F /* WALSnapshot.swift in Sources */,
 				AAA4DCA7230F1E0600C74B15 /* TableRecord.swift in Sources */,
 				56A2FA3D24424F4800E97D23 /* Export.swift in Sources */,
 				AAA4DCA8230F1E0600C74B15 /* Inflections+English.swift in Sources */,
@@ -4125,6 +4134,7 @@
 				569BBA4E229170F800478429 /* Inflections+English.swift in Sources */,
 				5656A81E2295B12F001FF3FF /* SQLAssociation.swift in Sources */,
 				5617294E223533F40006E219 /* EncodableRecord.swift in Sources */,
+				56B7EE832863781300C0525F /* WALSnapshot.swift in Sources */,
 				5698AD181DAAD17A0056AF8C /* FTS5Tokenizer.swift in Sources */,
 				56A2FA3624424D2A00E97D23 /* Export.swift in Sources */,
 				56B964B11DA51D010002DA19 /* FTS5TokenizerDescriptor.swift in Sources */,

GRDB/Core/Configuration.swift

@@ -275,7 +275,15 @@ public struct Configuration {
     ///
     /// Default: nil
     public var writeTargetQueue: DispatchQueue? = nil
-    
+
+#if os(iOS)
+    /// Sets whether GRDB will release memory when entering the background or
+    /// upon receiving a memory warning in iOS.
+    ///
+    /// Default: true
+    public var automaticMemoryManagement = true
+#endif
+
     // MARK: - Factory Configuration
 
     /// Creates a factory configuration

GRDB/Core/Database.swift

@@ -553,38 +553,6 @@ public final class Database: CustomStringConvertible, CustomDebugStringConvertib
         _readOnlyDepth > 0 || configuration.readonly
     }
 
-    // MARK: - Snapshots
-    
-    #if SQLITE_ENABLE_SNAPSHOT
-    /// Returns a snapshot that must be freed with `sqlite3_snapshot_free`.
-    ///
-    /// See <https://www.sqlite.org/c3ref/snapshot.html>
-    func takeVersionSnapshot() throws -> UnsafeMutablePointer<sqlite3_snapshot> {
-        var snapshot: UnsafeMutablePointer<sqlite3_snapshot>?
-        let code = withUnsafeMutablePointer(to: &snapshot) {
-            sqlite3_snapshot_get(sqliteConnection, "main", $0)
-        }
-        guard code == SQLITE_OK else {
-            throw DatabaseError(resultCode: code, message: lastErrorMessage)
-        }
-        if let snapshot = snapshot {
-            return snapshot
-        } else {
-            throw DatabaseError(resultCode: .SQLITE_INTERNAL) // WTF SQLite?
-        }
-    }
-    
-    func wasChanged(since initialSnapshot: UnsafeMutablePointer<sqlite3_snapshot>) throws -> Bool {
-        let secondSnapshot = try takeVersionSnapshot()
-        defer {
-            sqlite3_snapshot_free(secondSnapshot)
-        }
-        let cmp = sqlite3_snapshot_cmp(initialSnapshot, secondSnapshot)
-        assert(cmp <= 0, "Unexpected snapshot ordering")
-        return cmp < 0
-    }
-    #endif
-    
     // MARK: - Recording of the selected region
 
     func recordingSelection<T>(_ region: inout DatabaseRegion, _ block: () throws -> T) rethrows -> T {
@@ -1216,7 +1184,8 @@ public final class Database: CustomStringConvertible, CustomDebugStringConvertib
 
     // MARK: - Memory Management
 
-    func releaseMemory() {
+    public func releaseMemory() {
+        SchedulingWatchdog.preconditionValidQueue(self)
         sqlite3_db_release_memory(sqliteConnection)
         schemaCache.clear()
         internalStatementCache.clear()

GRDB/Core/DatabasePool.swift

@@ -103,7 +103,9 @@ public final class DatabasePool: DatabaseWriter {
         // Be a nice iOS citizen, and don't consume too much memory
         // See https://github.com/groue/GRDB.swift/#memory-management
         #if os(iOS)
-        setupMemoryManagement()
+        if configuration.automaticMemoryManagement {
+            setupMemoryManagement()
+        }
         #endif
     }
 
@@ -154,13 +156,6 @@ public final class DatabasePool: DatabaseWriter {
 
         return configuration
     }
-    
-    /// Blocks the current thread until all database connections have
-    /// executed the *body* block.
-    fileprivate func forEachConnection(_ body: (Database) -> Void) {
-        writer.sync(body)
-        readerPool?.forEach { $0.sync(body) }
-    }
 }
 
 #if swift(>=5.6) && canImport(_Concurrency)
@@ -172,19 +167,49 @@ extension DatabasePool {
 
     // MARK: - Memory management
 
-    /// Free as much memory as possible.
+    /// Frees as much memory as possible, by disposing non-essential memory from
+    /// the writer connection, and closing all reader connections.
+    ///
+    /// This method is synchronous, and blocks the current thread until all
+    /// database accesses are completed.
     ///
-    /// This method blocks the current thread until all database accesses
-    /// are completed.
+    /// - warning: This method can prevent concurrent reads from executing,
+    ///   until it returns. Prefer ``releaseMemoryEventually()`` if you intend
+    ///   to keep on using the database while releasing memory.
     public func releaseMemory() {
         // Release writer memory
         writer.sync { $0.releaseMemory() }
-        // Release readers memory by closing all connections
+        
+        // Release readers memory by closing all connections.
+        //
+        // We must use a barrier in order to guarantee that memory has been
+        // freed (reader connections closed) when the method exits, as
+        // documented.
+        //
+        // Without the barrier, connections would only close _eventually_ (after
+        // their eventual concurrent jobs have completed).
         readerPool?.barrier {
             readerPool?.removeAll()
         }
     }
 
+    /// Eventually frees as much memory as possible, by disposing non-essential
+    /// memory from the writer connection, and closing all reader connections.
+    ///
+    /// Unlike ``releaseMemory()``, this method does not prevent concurrent
+    /// database accesses when it is executing. But it does not notify when
+    /// non-essential memory has been freed.
+    public func releaseMemoryEventually() {
+        // Release readers memory by eventually closing all reader connections
+        // (they will close after their current jobs have completed).
+        readerPool?.removeAll()
+        
+        // Release writer memory eventually.
+        writer.async { db in
+            db.releaseMemory()
+        }
+    }
+    
     #if os(iOS)
     /// Listens to UIApplicationDidEnterBackgroundNotification and
     /// UIApplicationDidReceiveMemoryWarningNotification in order to release
@@ -216,22 +241,28 @@ extension DatabasePool {
 
         let task: UIBackgroundTaskIdentifier = application.beginBackgroundTask(expirationHandler: nil)
         if task == .invalid {
-            // Perform releaseMemory() synchronously.
+            // Release memory synchronously
             releaseMemory()
         } else {
-            // Perform releaseMemory() asynchronously.
-            DispatchQueue.global().async {
-                self.releaseMemory()
+            // Release memory eventually.
+            //
+            // We don't know when reader connections will be closed (because
+            // they may be currently in use), so we don't quite know when
+            // reader memory will be freed (which would be the ideal timing for
+            // ending our background task).
+            //
+            // So let's just end the background task after the writer connection
+            // has freed its memory. That's better than nothing.
+            releaseMemoryEventually()
+            writer.async { _ in
                 application.endBackgroundTask(task)
             }
         }
     }
 
     @objc
     private func applicationDidReceiveMemoryWarning(_ notification: NSNotification) {
-        DispatchQueue.global().async {
-            self.releaseMemory()
-        }
+        releaseMemoryEventually()
     }
     #endif
 }