Merge branch 'development'

Author: groue

CHANGELOG.md

@@ -7,6 +7,7 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 
 #### 6.x Releases
 
+- `6.28.x` Releases - [6.28.0](#6280)
 - `6.27.x` Releases - [6.27.0](#6270)
 - `6.26.x` Releases - [6.26.0](#6260)
 - `6.25.x` Releases - [6.25.0](#6250)
@@ -125,6 +126,15 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 
 ---
 
+## 6.28.0
+
+Released July 11, 2024
+
+- **New**: [#1570](https://github.com/groue/GRDB.swift/pull/1570) by [@groue](https://github.com/groue): Support single-value encoding
+- **New**: Added `QueryInterfaceRequest.deleteAndFetchIds(_:)` which returns the set of deleted ids.
+- **New**: Added `Set` methods `union`, `formUnion`, `intersection` and `formIntersection` that accept a cursor.
+- **New**: `DatabaseUUIDEncodingStrategy` is Sendable.
+
 ## 6.27.0
 
 Released April 21, 2024

Documentation/CommonTableExpressions.md

@@ -251,7 +251,7 @@ let rightCTE = ...
 let association = LeftRecord.association(
     to: rightCTE, 
     on: { left, right in
-        left[Column("x")] = right[Column("y")]
+        left[Column("x")] == right[Column("y")]
     })
 ```
 

GRDB.swift.podspec

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

GRDB/Core/Cursor.swift

@@ -195,6 +195,56 @@ extension Set {
         // database cursors.
         try cursor.forEach { insert($0) }
     }
+    
+    /// Returns a new set with the elements of both this set and the
+    /// given cursor.
+    ///
+    /// If the set already contains one or more elements that are also in
+    /// the cursor, the existing members are kept. If the cursor contains
+    /// multiple instances of equivalent elements, only the first instance
+    /// is kept.
+    ///
+    /// - parameter cursor: A cursor of elements.
+    /// - returns: A new set with the unique elements of this set
+    ///   and `cursor`.
+    public func union(_ cursor: some Cursor<Element>) throws -> Set<Element> {
+        var result = self
+        try result.formUnion(cursor)
+        return result
+    }
+
+    /// Inserts the elements of the given cursor into the set.
+    ///
+    /// If the set already contains one or more elements that are also in
+    /// the cursor, the existing members are kept. If the cursor contains
+    /// multiple instances of equivalent elements, only the first instance
+    /// is kept.
+    ///
+    /// - parameter cursor: A cursor of elements.
+    public mutating func formUnion(_ cursor: some Cursor<Element>) throws {
+        while let element = try cursor.next() {
+            insert(element)
+        }
+    }
+    
+    /// Returns a new set with the elements that are common to both this set
+    /// and the given cursor.
+    ///
+    /// - parameter cursor: A cursor of elements.
+    /// - returns: A new set.
+    public func intersection(_ cursor: some Cursor<Element>) throws -> Set<Element> {
+        var result = self
+        try result.formIntersection(cursor)
+        return result
+    }
+
+    /// Removes the elements of the set that aren’t also in the
+    /// given cursor.
+    ///
+    /// - parameter cursor: A cursor of elements.
+    public mutating func formIntersection(_ cursor: some Cursor<Element>) throws {
+        try formIntersection(Set(cursor))
+    }
 }
 
 extension Sequence {

GRDB/QueryInterface/Request/Association/AssociationAggregate.swift

@@ -366,6 +366,7 @@ extension AssociationToMany {
 /// ### Top-Level Functions
 ///
 /// - ``abs(_:)-43n8v``
+/// - ``cast(_:as:)-63ttx``
 /// - ``length(_:)-9dr2v``
 public struct AssociationAggregate<RowDecoder> {
     fileprivate let preparation: AssociationAggregatePreparation<RowDecoder>

GRDB/QueryInterface/Request/QueryInterfaceRequest.swift

@@ -61,6 +61,7 @@
 /// ### Batch Delete
 ///
 /// - ``deleteAll(_:)``
+/// - ``deleteAndFetchIds(_:)``
 /// - ``deleteAndFetchCursor(_:)``
 /// - ``deleteAndFetchAll(_:)``
 /// - ``deleteAndFetchSet(_:)``
@@ -528,7 +529,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - parameter selection: The returned columns (must not be empty).
@@ -561,7 +562,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - returns: A ``RecordCursor`` over the deleted records.
@@ -588,7 +589,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - returns: An array of deleted records.
@@ -614,7 +615,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - returns: A set of deleted records.
@@ -625,6 +626,41 @@ extension QueryInterfaceRequest {
     {
         try Set(deleteAndFetchCursor(db))
     }
+
+    /// Executes a `DELETE RETURNING` statement and returns the set of
+    /// deleted ids.
+    ///
+    /// For example:
+    ///
+    /// ```swift
+    /// // Fetch the ids of deleted players
+    /// // DELETE FROM player RETURNING id
+    /// let request = Player.all()
+    /// let deletedPlayerIds = try request.deleteAndFetchIds(db)
+    /// ```
+    ///
+    /// - important: Make sure you check the documentation of the `RETURNING`
+    ///   clause, which describes important limitations and caveats:
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
+    ///
+    /// - parameter db: A database connection.
+    /// - returns: A set of deleted ids.
+    /// - throws: A ``DatabaseError`` whenever an SQLite error occurs.
+    @available(iOS 13, macOS 10.15, tvOS 13, watchOS 6, *) // Identifiable
+    public func deleteAndFetchIds(_ db: Database)
+    throws -> Set<RowDecoder.ID>
+    where RowDecoder: TableRecord & Identifiable,
+    RowDecoder.ID: Hashable & DatabaseValueConvertible & StatementColumnConvertible
+    {
+        let primaryKey = try db.primaryKey(RowDecoder.databaseTableName)
+        GRDBPrecondition(
+            primaryKey.columns.count == 1,
+            "Fetching id requires a single-column primary key in the table \(databaseTableName)")
+        
+        let statement = try deleteAndFetchStatement(db, selection: [Column(primaryKey.columns[0])])
+        
+        return try RowDecoder.ID.fetchSet(statement)
+    }
 #else
     /// Returns a `DELETE RETURNING` prepared statement.
     ///
@@ -640,7 +676,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - parameter selection: The returned columns (must not be empty).
@@ -674,7 +710,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - returns: A ``RecordCursor`` over the deleted records.
@@ -702,7 +738,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - returns: An array of deleted records.
@@ -729,7 +765,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - returns: A set of deleted records.
@@ -741,6 +777,41 @@ extension QueryInterfaceRequest {
     {
         try Set(deleteAndFetchCursor(db))
     }
+
+    /// Executes a `DELETE RETURNING` statement and returns the set of
+    /// deleted ids.
+    ///
+    /// For example:
+    ///
+    /// ```swift
+    /// // Fetch the ids of deleted players
+    /// // DELETE FROM player RETURNING id
+    /// let request = Player.all()
+    /// let deletedPlayerIds = try request.deleteAndFetchIds(db)
+    /// ```
+    ///
+    /// - important: Make sure you check the documentation of the `RETURNING`
+    ///   clause, which describes important limitations and caveats:
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
+    ///
+    /// - parameter db: A database connection.
+    /// - returns: A set of deleted ids.
+    /// - throws: A ``DatabaseError`` whenever an SQLite error occurs.
+    @available(iOS 15, macOS 12, tvOS 15, watchOS 8, *) // SQLite 3.35.0+
+    public func deleteAndFetchIds(_ db: Database)
+    throws -> Set<RowDecoder.ID>
+    where RowDecoder: TableRecord & Identifiable,
+    RowDecoder.ID: Hashable & DatabaseValueConvertible & StatementColumnConvertible
+    {
+        let primaryKey = try db.primaryKey(RowDecoder.databaseTableName)
+        GRDBPrecondition(
+            primaryKey.columns.count == 1,
+            "Fetching id requires a single-column primary key in the table \(databaseTableName)")
+        
+        let statement = try deleteAndFetchStatement(db, selection: [Column(primaryKey.columns[0])])
+        
+        return try RowDecoder.ID.fetchSet(statement)
+    }
 #endif
 }
 
@@ -844,7 +915,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - parameter conflictResolution: A policy for conflict resolution.
@@ -893,7 +964,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - parameter conflictResolution: A policy for conflict resolution.
@@ -930,7 +1001,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - parameter conflictResolution: A policy for conflict resolution.
@@ -962,7 +1033,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - parameter conflictResolution: A policy for conflict resolution.
@@ -996,7 +1067,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - parameter conflictResolution: A policy for conflict resolution.
@@ -1046,7 +1117,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - parameter conflictResolution: A policy for conflict resolution.
@@ -1084,7 +1155,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - parameter conflictResolution: A policy for conflict resolution.
@@ -1117,7 +1188,7 @@ extension QueryInterfaceRequest {
     ///
     /// - important: Make sure you check the documentation of the `RETURNING`
     ///   clause, which describes important limitations and caveats:
-    ///   <https://www.sqlite.org/lang_returning.html>.
+    ///   <https://www.sqlite.org/lang_returning.html#limitations_and_caveats>.
     ///
     /// - parameter db: A database connection.
     /// - parameter conflictResolution: A policy for conflict resolution.

GRDB/QueryInterface/SQL/SQLExpression.swift

@@ -2167,6 +2167,7 @@ extension SQLExpressible where Self == Column {
 /// - ``average(_:)``
 /// - ``average(_:filter:)``
 /// - ``capitalized``
+/// - ``cast(_:as:)-1dmu3``
 /// - ``count(_:)``
 /// - ``count(distinct:)``
 /// - ``dateTime(_:_:)``