Merge pull request #1079 from groue/dev/async

Async / Await

Author: groue

CHANGELOG.md

@@ -85,12 +85,16 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 
 ## Next Release
 
+- **New**: :star: [#1079](https://github.com/groue/GRDB.swift/pull/1079) by [@groue](https://github.com/groue): Async / Await
 - **New**: `DatabaseRegion(table: tableName)` is deprecated. Use `Table(tableName)` instead.
 - **New**: The `ABS` and `LENGTH` SQL functions are now available on association aggregates, through `abs(aggregate)` and `length(aggregate)`.
 - **New**: Support for the [`TOTAL` aggregate function](https://www.sqlite.org/lang_aggfunc.html#sumunc). You can use `total` in Swift, at all places `sum` is available.
 - **New**: `ValueObservation.removeDuplicates(by:)` with a closure argument.
 - **New**: Testing for the existence of an associated record with `TableAlias.exists` now supports associated views, and associated tables WITHOUT ROWID that have a compound primary key.
 - **Fixed**: `Database.primaryKey(_:)` throws when given the name of a view.
+- **Documentation Update**: :star: The [Concurrency Guide](Documentation/Concurrency.md) was updated for the new support for asynchronous Swift.
+- **Documentation Update**: :star: [GRDBAsyncDemo](Documentation/DemoApps/GRDBAsyncDemo/README.md) is a new SwiftUI demo app that uses the new async apis.
+- **Documentation Update**: A new FAQ gives hints for avoiding a [Mutation of captured var in concurrently-executing code](README.md##mutation-of-captured-var-in-concurrently-executing-code) compiler error.
 
 ## 5.16.0
 

Documentation/Concurrency.md

@@ -132,7 +132,27 @@ try dbQueue.write { db in
 }
 ```
 
-:twisted_rightwards_arrows: **An async access does not block the current thread.** Instead, it notifies you when the database operations are completed. There are three ways to access the database asynchronously:
+:twisted_rightwards_arrows: **An async access does not block the current thread.** Instead, it notifies you when the database operations are completed. There are four ways to access the database asynchronously:
+
+<details>
+    <summary><b>Swift concurrency</b> (async/await)</summary>
+
+[**:fire: EXPERIMENTAL**](../README.md#what-are-experimental-features) GRDB support for Swift concurrency requires Xcode 13.2+.
+
+```swift
+let playerCount = try await dbQueue.read { db in
+    try Player.fetchCount(db)
+}
+
+let newPlayerCount = try await dbQueue.write { db -> Int in
+    try Player(id: 12, name: "Arthur").insert(db)
+    return try Player.fetchCount(db)
+}
+```
+
+Note the identical method names: `read`, `write`. The async version is only available in async Swift functions.
+
+</details>
 
 <details>
     <summary><b>Combine publishers</b></summary>
@@ -205,7 +225,7 @@ During one async access, all individual database operations grouped inside (fetc
 
 ```swift
 // One asynchronous access...
-dbQueue.writePublisher { db in
+try await dbQueue.write { db in
     // ... always performs synchronous database operations:
     try Player(...).insert(db)
     try Player(...).insert(db)
@@ -237,7 +257,7 @@ Some applications need to relax this safety net, in order to achieve specific SQ
     try dbQueue.writeWithoutTransaction { db in ... }
     ```
 
-    You can also use `asyncWriteWithoutTransaction`.
+    `writeWithoutTransaction` is also available as an `async` function. You can also use `asyncWriteWithoutTransaction`.
 
 - **Write outside of any transaction, and prevents concurrent reads**  
   (Lifted guarantee: [Write Transactions])
@@ -252,7 +272,7 @@ Some applications need to relax this safety net, in order to achieve specific SQ
 
     You will use this method, for example, when you [change the password](../README.md#changing-the-passphrase-of-an-encrypted-database) of an encrypted database.
 
-    You can also use `asyncBarrierWriteWithoutTransaction`.
+    `barrierWriteWithoutTransaction` is also available as an `async` function. You can also use `asyncBarrierWriteWithoutTransaction`.
 
 - **Reentrant write outside of any transaction**  
   (Lifted guarantees: [Write Transactions], [Non-Reentrancy])
@@ -279,7 +299,7 @@ Some applications need to relax this safety net, in order to achieve specific SQ
     try dbQueue.unsafeRead { db in ... }
     ```
 
-    `unsafeRead` has no async version.
+    `unsafeRead` is also available as an `async` function.
 
 - **Reentrant read, outside of any transaction**  
   (Lifted guarantees: [Isolated Reads], [Forbidden Writes], [Non-Reentrancy])

Documentation/DemoApps/GRDBAsyncDemo/GRDBAsyncDemo.xcodeproj/project.pbxproj

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>IDEDidComputeMac32BitWarning</key>
+	<true/>
+</dict>
+</plist>

Documentation/DemoApps/GRDBAsyncDemo/GRDBAsyncDemo.xcodeproj/project.xcworkspace/contents.xcworkspacedata

@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1230"
+   version = "1.3">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "567C3E152520B6DE0011F6E9"
+               BuildableName = "GRDBAsyncDemo.app"
+               BlueprintName = "GRDBAsyncDemo"
+               ReferencedContainer = "container:GRDBAsyncDemo.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES">
+      <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "56026C9725B8A7D000D1DF3F"
+               BuildableName = "GRDBAsyncDemoTests.xctest"
+               BlueprintName = "GRDBAsyncDemoTests"
+               ReferencedContainer = "container:GRDBAsyncDemo.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "78E2F9E2261EEC22005D1F7F"
+               BuildableName = "GRDBAsyncDemoUITests.xctest"
+               BlueprintName = "GRDBAsyncDemoUITests"
+               ReferencedContainer = "container:GRDBAsyncDemo.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "567C3E152520B6DE0011F6E9"
+            BuildableName = "GRDBAsyncDemo.app"
+            BlueprintName = "GRDBAsyncDemo"
+            ReferencedContainer = "container:GRDBAsyncDemo.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "567C3E152520B6DE0011F6E9"
+            BuildableName = "GRDBAsyncDemo.app"
+            BlueprintName = "GRDBAsyncDemo"
+            ReferencedContainer = "container:GRDBAsyncDemo.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>

Documentation/DemoApps/GRDBAsyncDemo/GRDBAsyncDemo.xcodeproj/project.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist

@@ -0,0 +1,168 @@
+import Foundation
+import GRDB
+
+/// AppDatabase lets the application access the database.
+///
+/// It applies the pratices recommended at
+/// <https://github.com/groue/GRDB.swift/blob/master/Documentation/GoodPracticesForDesigningRecordTypes.md>
+struct AppDatabase {
+    /// Creates an `AppDatabase`, and make sure the database schema is ready.
+    init(_ dbWriter: DatabaseWriter) throws {
+        self.dbWriter = dbWriter
+        try migrator.migrate(dbWriter)
+    }
+    
+    /// Provides access to the database.
+    ///
+    /// Application can use a `DatabasePool`, while SwiftUI previews and tests
+    /// can use a fast in-memory `DatabaseQueue`.
+    ///
+    /// See <https://github.com/groue/GRDB.swift/blob/master/README.md#database-connections>
+    private let dbWriter: DatabaseWriter
+    
+    /// The DatabaseMigrator that defines the database schema.
+    ///
+    /// See <https://github.com/groue/GRDB.swift/blob/master/Documentation/Migrations.md>
+    private var migrator: DatabaseMigrator {
+        var migrator = DatabaseMigrator()
+        
+        #if DEBUG
+        // Speed up development by nuking the database when migrations change
+        // See https://github.com/groue/GRDB.swift/blob/master/Documentation/Migrations.md#the-erasedatabaseonschemachange-option
+        migrator.eraseDatabaseOnSchemaChange = true
+        #endif
+        
+        migrator.registerMigration("createPlayer") { db in
+            // Create a table
+            // See https://github.com/groue/GRDB.swift#create-tables
+            try db.create(table: "player") { t in
+                t.autoIncrementedPrimaryKey("id")
+                t.column("name", .text).notNull()
+                t.column("score", .integer).notNull()
+            }
+        }
+        
+        // Migrations for future application versions will be inserted here:
+        // migrator.registerMigration(...) { db in
+        //     ...
+        // }
+        
+        return migrator
+    }
+}
+
+// MARK: - Database Access: Writes
+
+extension AppDatabase {
+    /// A validation error that prevents some players from being saved into
+    /// the database.
+    enum ValidationError: LocalizedError {
+        case missingName
+        
+        var errorDescription: String? {
+            switch self {
+            case .missingName:
+                return "Please provide a name"
+            }
+        }
+    }
+    
+    /// Saves (inserts or updates) a player. When the method returns, the
+    /// player is present in the database, and its id is not nil.
+    func savePlayer(_ player: inout Player) async throws {
+        if player.name.isEmpty {
+            throw ValidationError.missingName
+        }
+        player = try await dbWriter.write { [player] db in
+            try player.saved(db)
+        }
+    }
+    
+    /// Delete the specified players
+    func deletePlayers(ids: [Int64]) async throws {
+        try await dbWriter.write { db in
+            _ = try Player.deleteAll(db, ids: ids)
+        }
+    }
+    
+    /// Delete all players
+    func deleteAllPlayers() async throws {
+        try await dbWriter.write { db in
+            _ = try Player.deleteAll(db)
+        }
+    }
+    
+    /// Refresh all players (by performing some random changes, for demo purpose).
+    func refreshPlayers() async throws {
+        try await dbWriter.write { db in
+            if try Player.all().isEmpty(db) {
+                // When database is empty, insert new random players
+                try createRandomPlayers(db)
+            } else {
+                // Insert a player
+                if Bool.random() {
+                    _ = try Player.makeRandom().inserted(db) // insert but ignore inserted id
+                }
+                
+                // Delete a random player
+                if Bool.random() {
+                    try Player.order(sql: "RANDOM()").limit(1).deleteAll(db)
+                }
+                
+                // Update some players
+                for var player in try Player.fetchAll(db) where Bool.random() {
+                    try player.updateChanges(db) {
+                        $0.score = Player.randomScore()
+                    }
+                }
+            }
+        }
+    }
+    
+    /// Create random players if the database is empty.
+    func createRandomPlayersIfEmpty() throws {
+        try dbWriter.write { db in
+            if try Player.all().isEmpty(db) {
+                try createRandomPlayers(db)
+            }
+        }
+    }
+
+    static let uiTestPlayers = [
+        Player(id: nil, name: "Arthur", score: 5),
+        Player(id: nil, name: "Barbara", score: 6),
+        Player(id: nil, name: "Craig", score: 8),
+        Player(id: nil, name: "David", score: 4),
+        Player(id: nil, name: "Elena", score: 1),
+        Player(id: nil, name: "Frederik", score: 2),
+        Player(id: nil, name: "Gilbert", score: 7),
+        Player(id: nil, name: "Henriette", score: 3)]
+
+    func createPlayersForUITests() throws {
+        try dbWriter.write { db in
+            try AppDatabase.uiTestPlayers.forEach { player in
+                _ = try player.inserted(db) // insert but ignore inserted id
+            }
+        }
+    }
+    
+    /// Support for `createRandomPlayersIfEmpty()` and `refreshPlayers()`.
+    private func createRandomPlayers(_ db: Database) throws {
+        for _ in 0..<8 {
+            _ = try Player.makeRandom().inserted(db) // insert but ignore inserted id
+        }
+    }
+}
+
+// MARK: - Database Access: Reads
+
+// This demo app does not provide any specific reading method, and instead
+// gives an unrestricted read-only access to the rest of the application.
+// In your app, you are free to choose another path, and define focused
+// reading methods.
+extension AppDatabase {
+    /// Provides a read-only access to the database
+    var databaseReader: DatabaseReader {
+        dbWriter
+    }
+}