Merge branch 'groue:master' into sqlcipher

Author: marcprux

CHANGELOG.md

@@ -7,6 +7,7 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 
 #### 7.x Releases
 
+- `7.4.x` Releases - [7.4.0](#740) - [7.4.1](#741)
 - `7.3.x` Releases - [7.3.0](#730)
 - `7.2.x` Releases - [7.2.0](#720)
 - `7.1.x` Releases - [7.1.0](#710)
@@ -135,6 +136,19 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 
 ---
 
+## 7.4.1
+
+Released March 28, 2025
+
+- Removed a compiler warning
+
+## 7.4.0
+
+Released March 22, 2025
+
+- **New**: Add the MIN and MAX multi-argument SQL functions to the query interface by [@groue](https://github.com/groue) in [#1745](https://github.com/groue/GRDB.swift/pull/1745)
+- **Fixed**: Transaction observers are not impacted by Task Cancellation by [@groue](https://github.com/groue) in [#1747](https://github.com/groue/GRDB.swift/pull/1747). This fixes unexpected `ValueObservation` failures in applications that perform asynchronous writes.
+
 ## 7.3.0
 
 Released February 23, 2025

GRDB.swift.podspec

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

GRDB/Core/Database+Statements.swift

@@ -494,11 +494,9 @@ extension Database {
 
         switch ResultCode(rawValue: resultCode) {
         case .SQLITE_INTERRUPT, .SQLITE_ABORT:
-            if suspensionMutex.load().isCancelled {
-                // The only error that a user sees when a Task is cancelled
-                // is CancellationError.
-                throw CancellationError()
-            }
+            // The only error that a user sees when a Task is cancelled
+            // is CancellationError.
+            try suspensionMutex.load().checkCancellation()
         default:
             break
         }

GRDB/Core/Database.swift

@@ -341,10 +341,22 @@ public final class Database: CustomStringConvertible, CustomDebugStringConvertib
 
         /// If true, the database access has been cancelled.
         var isCancelled: Bool
+        
+        /// If true, the database throws an error when it is cancelled.
+        var interruptsWhenCancelled: Bool
+        
+        func checkCancellation() throws {
+            if isCancelled, interruptsWhenCancelled {
+                throw CancellationError()
+            }
+        }
     }
 
     /// Support for `checkForSuspensionViolation(from:)`
-    let suspensionMutex = Mutex(Suspension(isSuspended: false, isCancelled: false))
+    let suspensionMutex = Mutex(Suspension(
+        isSuspended: false,
+        isCancelled: false,
+        interruptsWhenCancelled: true))
 
     // MARK: - Transaction Date
 
@@ -1222,7 +1234,7 @@ public final class Database: CustomStringConvertible, CustomDebugStringConvertib
             }
 
             suspension.isCancelled = true
-            return true
+            return suspension.interruptsWhenCancelled
         }
 
         if needsInterrupt {
@@ -1237,6 +1249,24 @@ public final class Database: CustomStringConvertible, CustomDebugStringConvertib
         }
     }
 
+    /// Within the given closure, Task cancellation does not interrupt
+    /// database accesses.
+    func ignoringCancellation<T>(_ value: () throws -> T) rethrows -> T {
+        let previous = suspensionMutex.withLock {
+            let previous = $0.interruptsWhenCancelled
+            $0.interruptsWhenCancelled = false
+            return previous
+        }
+        
+        defer {
+            suspensionMutex.withLock {
+                $0.interruptsWhenCancelled = previous
+            }
+        }
+        
+        return try value()
+    }
+    
     /// Support for `checkForSuspensionViolation(from:)`
     private func journalMode() throws -> String {
         if let journalMode = journalModeCache {
@@ -1303,7 +1333,7 @@ public final class Database: CustomStringConvertible, CustomDebugStringConvertib
         let interrupt: Interrupt? = try suspensionMutex.withLock { suspension in
             // Check for cancellation first, so that the only error that
             // a user sees when a Task is cancelled is CancellationError.
-            if suspension.isCancelled {
+            if suspension.isCancelled, suspension.interruptsWhenCancelled {
                 return .cancel
             }
 

GRDB/Core/TransactionObserver.swift

@@ -549,8 +549,12 @@ class DatabaseObservationBroker {
         savepointStack.clear()
 
         if !database.isReadOnly {
-            for observation in transactionObservations {
-                observation.databaseDidCommit(database)
+            // Observers must be able to access the database, even if the
+            // task that has performed the commit is cancelled.
+            database.ignoringCancellation {
+                for observation in transactionObservations {
+                    observation.databaseDidCommit(database)
+                }
             }
         }
 
@@ -613,8 +617,13 @@ class DatabaseObservationBroker {
 
         if notifyTransactionObservers {
             assert(!database.isReadOnly, "Read-only transactions are not notified")
-            for observation in transactionObservations {
-                observation.databaseDidRollback(database)
+            
+            // Observers must be able to access the database, even if the
+            // task that has performed the commit is cancelled.
+            database.ignoringCancellation {
+                for observation in transactionObservations {
+                    observation.databaseDidRollback(database)
+                }
             }
         }
         databaseDidEndTransaction()

GRDB/Documentation.docc/Migrations.md

@@ -94,6 +94,26 @@ migrator.registerMigration("Create authors") { db in
 }
 ```
 
+#### How to Rename a Foreign Key
+
+When a migration **renames a foreign key**, make sure the migration runs with `.immediate` foreign key checks, in order to avoid database integrity problems:
+
+```swift
+// IMPORTANT: rename foreign keys with immediate foreign key checks.
+migrator.registerMigration("Guilds", foreignKeyChecks: .immediate) { db in
+    try db.rename(table: "team", to: "guild")
+    
+    try db.alter(table: "player") { t in
+        // Rename a foreign key
+        t.rename(column: "teamId", to: "guildId")
+    }
+}
+```
+
+Note: migrations that run with `.immediate` foreign key checks can not be used to recreated database tables, as described below. When needed, define two migrations instead of one.
+
+#### How to Recreate a Database Table 
+
 When you need to modify a table in a way that is not directly supported by SQLite, or not available on your target operating system, you will need to recreate the database table.
 
 For example:
@@ -113,19 +133,39 @@ migrator.registerMigration("Add NOT NULL check on author.name") { db in
 
 The detailed sequence of operations for recreating a database table from a migration is:
 
-1. When relevant, remember the format of all indexes, triggers, and views associated with table X. This information will be needed in steps 6 and 7 below. One way to do this is to run a query like the following: `SELECT type, sql FROM sqlite_schema WHERE tbl_name='X'`.
+1. When relevant, remember the format of all indexes, triggers, and views associated with table `X`. This information will be needed in steps 6 below. One way to do this is to run the following statement and examine the output in the console:
 
-2. Use `CREATE TABLE` to construct a new table "new_X" that is in the desired revised format of table X. Make sure that the name "new_X" does not collide with any existing table name, of course.
+    ```swift
+    try db.dumpSQL("SELECT type, sql FROM sqlite_schema WHERE tbl_name='X'")
+    ```
 
-3. Transfer content from X into new_X using a statement like: `INSERT INTO new_X SELECT ... FROM X`.
+2. Construct a new table `new_X` that is in the desired revised format of table `X`. Make sure that the name `new_X` does not collide with any existing table name, of course.
 
-4. Drop the old table X: `DROP TABLE X`.
+    ```swift
+    try db.create(table: "new_X") { t in ... }
+    ```
+
+3. Transfer content from `X` into `new_X` using a statement like:
+
+    ```swift
+    try db.execute(sql: "INSERT INTO new_X SELECT ... FROM X")
+    ```
+
+4. Drop the old table `X`:
+    
+    ```swift
+    try db.drop(table: "X")
+    ```
 
-5. Change the name of new_X to X using: `ALTER TABLE new_X RENAME TO X`.
+5. Change the name of `new_X` to `X` using:
+
+    ```swift
+    try db.rename(table: "new_X", to: "X")
+    ```
 
-6. When relevant, use `CREATE INDEX`, `CREATE TRIGGER`, and `CREATE VIEW` to reconstruct indexes, triggers, and views associated with table X. Perhaps use the old format of the triggers, indexes, and views saved from step 3 above as a guide, making changes as appropriate for the alteration.
+6. When relevant, reconstruct indexes, triggers, and views associated with table `X`.
 
-7. If any views refer to table X in a way that is affected by the schema change, then drop those views using `DROP VIEW` and recreate them with whatever changes are necessary to accommodate the schema change using `CREATE VIEW`.
+7. If any views refer to table `X` in a way that is affected by the schema change, then drop those views using `DROP VIEW` and recreate them with whatever changes are necessary to accommodate the schema change using `CREATE VIEW`.
 
 > Important: When recreating a table, be sure to follow the above procedure exactly, in the given order, or you might corrupt triggers, views, and foreign key constraints.
 >

GRDB/QueryInterface/SQL/SQLExpression.swift

@@ -2209,8 +2209,10 @@ extension SQLExpressible where Self == Column {
 /// - ``localizedLowercased``
 /// - ``localizedUppercased``
 /// - ``lowercased``
+/// - ``min(_:_:_:)``
 /// - ``min(_:)``
 /// - ``min(_:filter:)``
+/// - ``max(_:_:_:)``
 /// - ``max(_:)``
 /// - ``max(_:filter:)``
 /// - ``sum(_:)``