Merge branch 'development'

Author: groue

CHANGELOG.md

@@ -7,7 +7,7 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 
 #### 6.x Releases
 
-- `6.0.0` Betas - [6.0.0-beta](#600-beta)
+- `6.0.0` Betas - [6.0.0-beta](#600-beta) | [6.0.0-beta.2](#600-beta2)
 
 #### 5.x Releases
 
@@ -97,6 +97,13 @@ GRDB adheres to [Semantic Versioning](https://semver.org/), with one exception:
 
 ---
 
+## 6.0.0-beta.2
+
+Released August 23, 2022 • [diff](https://github.com/groue/GRDB.swift/compare/v6.0.0-beta...v6.0.0-beta.2)
+
+- **New**: Extended UPSERT apis with the ability to define the conflict target, and the assignments performed in case of conflicts.
+- **Documentation**: A new [Upsert](README.md#upsert) chapter describes upserts in detail.
+
 ## 6.0.0-beta
 
 Released August 21, 2022 • [diff](https://github.com/groue/GRDB.swift/compare/v5.26.0...v6.0.0-beta)

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/6.0.0-beta/Structs/StatementArguments.html):
+FTS3Pattern are regular [values](../README.md#values). You can use them as query [arguments](http://groue.github.io/GRDB.swift/docs/6.0.0-beta.2/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/6.0.0-beta/Structs/StatementArguments.html):
+FTS5Pattern are regular [values](../README.md#values). You can use them as query [arguments](http://groue.github.io/GRDB.swift/docs/6.0.0-beta.2/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/6.0.0-beta/Structs/DatabaseMigrator.html) for more migrator methods.
+See the [DatabaseMigrator reference](http://groue.github.io/GRDB.swift/docs/6.0.0-beta.2/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  = '6.0.0-beta'
+  s.version  = '6.0.0-beta.2'
 
   s.license  = { :type => 'MIT', :file => 'LICENSE' }
   s.summary  = 'A toolkit for SQLite databases, with a focus on application development.'

GRDB/Core/Database+Schema.swift

@@ -1045,7 +1045,7 @@ public struct PrimaryKeyInfo {
     ///
     /// Returns nil for WITHOUT ROWID tables with a multi-columns primary key
     var fastPrimaryKeyColumn: String? {
-        if let rowIDColumn = rowIDColumn {
+        if let rowIDColumn {
             // Prefer the user-provided name of the rowid
             //
             //  // CREATE TABLE player (id INTEGER PRIMARY KEY, ...)

GRDB/QueryInterface/Request/QueryInterfaceRequest.swift

@@ -1017,10 +1017,19 @@ extension QueryInterfaceRequest {
 ///     }
 public struct ColumnAssignment {
     var columnName: String
-    var value: SQLExpression
 
-    func sql(_ context: SQLGenerationContext) throws -> String {
-        try Column(columnName).sqlExpression.sql(context) + " = " + value.sql(context)
+    /// If nil, this is a "don't assign" assignment.
+    var value: SQLExpression?
+    
+    init(columnName: String, value: SQLExpression? = nil) {
+        self.columnName = columnName
+        self.value = value
+    }
+    
+    /// If nil, there's nothing to assign to.
+    func sql(_ context: SQLGenerationContext) throws -> String? {
+        guard let value else { return nil }
+        return try Column(columnName).sqlExpression.sql(context) + " = " + value.sql(context)
     }
 }
 
@@ -1039,6 +1048,11 @@ extension ColumnExpression {
     public func set(to value: (any SQLExpressible)?) -> ColumnAssignment {
         ColumnAssignment(columnName: name, value: value?.sqlExpression ?? .null)
     }
+    
+    /// Returns an assignment that does not modify this column.
+    public var noOverwrite: ColumnAssignment {
+        ColumnAssignment(columnName: name, value: nil)
+    }
 }
 
 /// Creates an assignment that adds a value

GRDB/QueryInterface/SQLGeneration/SQLQueryGenerator.swift

@@ -288,12 +288,6 @@ struct SQLQueryGenerator: Refinable {
                     selection: selection)
             }
 
-            // Check for empty assignments after all programmer errors have
-            // been checked.
-            if assignments.isEmpty {
-                return nil
-            }
-            
             let context = SQLGenerationContext(db, aliases: relation.allAliases, ctes: relation.ctes)
 
             var sql = try commonTableExpressionsPrefix(context)
@@ -305,10 +299,13 @@ struct SQLQueryGenerator: Refinable {
 
             sql += try relation.source.sql(context)
 
-            sql += " SET "
-            sql += try assignments
-                .map { try $0.sql(context) }
+            let updateSQL = try assignments
+                .compactMap { try $0.sql(context) }
                 .joined(separator: ", ")
+            if updateSQL.isEmpty {
+                return nil
+            }
+            sql += " SET \(updateSQL)"
 
             if let filter = try relation.filterPromise?.resolve(db) {
                 sql += " WHERE "
@@ -351,12 +348,6 @@ struct SQLQueryGenerator: Refinable {
         selection: [any SQLSelectable])
     throws -> Statement?
     {
-        // Check for empty assignments after all programmer errors have
-        // been checked.
-        if assignments.isEmpty {
-            return nil
-        }
-        
         let tableName = relation.source.tableName
         let alias = TableAlias(tableName: tableName)
         let context = SQLGenerationContext(db, aliases: [alias])
@@ -374,10 +365,13 @@ struct SQLQueryGenerator: Refinable {
         sql += tableName.quotedDatabaseIdentifier
 
         // SET column = value...
-        sql += " SET "
-        sql += try assignments
-            .map { try $0.sql(context) }
+        let updateSQL = try assignments
+            .compactMap { try $0.sql(context) }
             .joined(separator: ", ")
+        if updateSQL.isEmpty {
+            return nil
+        }
+        sql += " SET \(updateSQL)"
 
         // WHERE id IN (SELECT id FROM ...)
         sql += " WHERE "

GRDB/Record/MutablePersistableRecord+DAO.swift

@@ -41,34 +41,93 @@ final class DAO<Record: MutablePersistableRecord> {
 
     func upsertStatement(
         _ db: Database,
-        conflictTarget conflictTargetColumns: [String],
+        onConflict conflictTargetColumns: [String],
+        doUpdate assignments: ((_ excluded: TableAlias) -> [ColumnAssignment])?,
+        updateCondition: ((_ existing: TableAlias, _ excluded: TableAlias) -> any SQLExpressible)? = nil,
         returning selection: [any SQLSelectable])
     throws -> Statement
     {
-        // Don't update columns not present in the persistenceContainer
-        // Don't update columns not present in conflictTargetColumns
-        // Don't update primary key columns
-        let lowercaseUpdatedColumns = Set(persistenceContainer.columns.map { $0.lowercased() })
-            .subtracting(primaryKey.columns.map { $0.lowercased() })
-            .subtracting(conflictTargetColumns.map { $0.lowercased() })
-        
-        var updatedColumns: [String] = []
+        // INSERT
+        let insertedColumns = persistenceContainer.columns
+        let columnsSQL = insertedColumns.map(\.quotedDatabaseIdentifier).joined(separator: ", ")
+        let valuesSQL = databaseQuestionMarks(count: insertedColumns.count)
+        var sql = """
+            INSERT INTO \(databaseTableName.quotedDatabaseIdentifier) (\(columnsSQL)) \
+            VALUES (\(valuesSQL))
+            """
         var arguments = StatementArguments(persistenceContainer.values)
+        
+        // ON CONFLICT
+        if conflictTargetColumns.isEmpty {
+            sql += " ON CONFLICT"
+        } else {
+            let targetSQL = conflictTargetColumns
+                .map { $0.quotedDatabaseIdentifier }
+                .joined(separator: ", ")
+            sql += " ON CONFLICT(\(targetSQL))"
+        }
+        
+        // DO UPDATE SET
+        // We update explicit assignments from the `assignments` parameter.
+        // Other columns are overwritten by inserted values. This makes sure
+        // that no information stored in the record is lost, unless explicitly
+        // requested by the user.
+        sql += " DO UPDATE SET "
+        let excluded = TableAlias(name: "excluded")
+        var assignments = assignments?(excluded) ?? []
+        let lowercaseExcludedColumns = Set(primaryKey.columns.map { $0.lowercased() })
+            .union(conflictTargetColumns.map { $0.lowercased() })
         for column in persistenceContainer.columns {
-            if lowercaseUpdatedColumns.contains(column.lowercased()) {
-                updatedColumns.append(column)
-                arguments += [persistenceContainer.databaseValue(at: column)]
+            let lowercasedColumn = column.lowercased()
+            if lowercaseExcludedColumns.contains(lowercasedColumn) {
+                // excluded (primary key or conflict target)
+                continue
+            }
+            if assignments.contains(where: { $0.columnName.lowercased() == lowercasedColumn }) {
+                // already updated from the `assignments` argument
+                continue
             }
+            // overwrite
+            assignments.append(Column(column).set(to: excluded[column]))
+        }
+        let context = SQLGenerationContext(db)
+        let updateSQL = try assignments
+            .compactMap { try $0.sql(context) }
+            .joined(separator: ", ")
+        if updateSQL.isEmpty {
+            if !selection.isEmpty {
+                // User has asked that no column was overwritten or updated.
+                // In case of conflict, the upsert would do nothing, and return
+                // nothing: <https://sqlite.org/forum/forumpost/1ead75e2c45de9a5>.
+                //
+                // But we have a RETURNING clause, so we WANT values to be
+                // returned, and we MUST prevent the upsert statement from
+                // return nothing. The RETURNING clause is how, for example, we
+                // fetch the rowid of the upserted record, and feed record
+                // callbacks such as `didInsert`. Not returning any value would
+                // be a GRDB bug.
+                //
+                // So let's make SURE something is returned, and to do so, let's
+                // update one column. The first column of the primary key should
+                // be ok.
+                let column = primaryKey.columns[0].quotedDatabaseIdentifier
+                sql += "\(column) = \(column)"
+            }
+        } else {
+            sql += updateSQL
+            arguments += context.arguments
         }
 
-        let query = UpsertQuery(
-            tableName: databaseTableName,
-            insertedColumns: persistenceContainer.columns,
-            conflictTargetColumns: conflictTargetColumns,
-            updatedColumns: updatedColumns)
+        // WHERE
+        let existing = TableAlias(name: databaseTableName)
+        if let condition = updateCondition?(existing, excluded) {
+            let context = SQLGenerationContext(db)
+            sql += try " WHERE " + condition.sqlExpression.sql(context)
+            arguments += context.arguments
+        }
 
         return try makeStatement(
-            sql: query.sql,
+            sql: sql,
             checkedArguments: arguments,
             returning: selection)
     }
@@ -240,47 +299,6 @@ extension InsertQuery {
     }
 }
 
-// MARK: - UpsertQuery
-
-private struct UpsertQuery: Hashable {
-    let tableName: String
-    let insertedColumns: [String]
-    let conflictTargetColumns: [String]
-    let updatedColumns: [String]
-}
-
-extension UpsertQuery {
-    @ReadWriteBox private static var sqlCache: [UpsertQuery: String] = [:]
-    var sql: String {
-        if let sql = Self.sqlCache[self] {
-            return sql
-        }
-        
-        let columnsSQL = insertedColumns.map(\.quotedDatabaseIdentifier).joined(separator: ", ")
-        let valuesSQL = databaseQuestionMarks(count: insertedColumns.count)
-        
-        let onConflictSQL: String
-        if conflictTargetColumns.isEmpty {
-            onConflictSQL = "ON CONFLICT"
-        } else {
-            let targetSQL = conflictTargetColumns
-                .map { $0.quotedDatabaseIdentifier }
-                .joined(separator: ", ")
-            onConflictSQL = "ON CONFLICT(\(targetSQL))"
-        }
-        
-        let updateSQL = updatedColumns.map { "\($0.quotedDatabaseIdentifier)=?" }.joined(separator: ", ")
-        
-        let sql = """
-            INSERT INTO \(tableName.quotedDatabaseIdentifier) (\(columnsSQL)) \
-            VALUES (\(valuesSQL)) \
-            \(onConflictSQL) DO UPDATE SET \(updateSQL)
-            """
-        Self.sqlCache[self] = sql
-        return sql
-    }
-}
-
 // MARK: - UpdateQuery
 
 private struct UpdateQuery: Hashable {

GRDB/Record/MutablePersistableRecord+Insert.swift

@@ -460,7 +460,7 @@ extension MutablePersistableRecord {
         // This allows the Record class to set its `hasDatabaseChanges` property
         // to false in its `aroundInsert` callback.
         var persistenceContainer = dao.persistenceContainer
-        if let rowIDColumn = rowIDColumn {
+        if let rowIDColumn {
             persistenceContainer[caseInsensitive: rowIDColumn] = rowid
         }