Implement Upsert [#482]

# Problem

Apps need the ability to insert or, if the row already exists, update the existing row. This is commonly called "upsert" and is [documented for SQLite here](https://www.sqlite.org/lang_UPSERT.html). The existing "replace" on conflict clause for `insert()` often does not have the desired behavior. It will cascade (with deletes, if specified) along foreign keys if the value exists and has to be replaced ([see Issue 842](#842)).

# Solution

Create an `upsert()` method for queries. The basic form allows for the fallback setters to be manually specified. A slightly more ergonomic version will compute the setters from the inserted values by removing the "conflicting" column, and then using the inserted values via the "excluded" qualifier. Additionally, an `Encodable` version of `upsert` is provided.

Author: andyfinnell

Documentation/Index.md

@@ -35,6 +35,7 @@
       - [Sorting Rows](#sorting-rows)
       - [Limiting and Paging Results](#limiting-and-paging-results)
       - [Aggregation](#aggregation)
+  - [Upserting Rows](#upserting-rows)
   - [Updating Rows](#updating-rows)
   - [Deleting Rows](#deleting-rows)
   - [Transactions and Savepoints](#transactions-and-savepoints)
@@ -1098,6 +1099,33 @@ let count = try db.scalar(users.filter(name != nil).count)
 > // SELECT count(DISTINCT "name") FROM "users"
 > ```
 
+## Upserting Rows
+
+We can upsert rows into a table by calling a [query’s](#queries) `upsert`
+function with a list of [setters](#setters)—typically [typed column
+expressions](#expressions) and values (which can also be expressions)—each
+joined by the `<-` operator. Upserting is like inserting, except if there is a 
+conflict on the specified column value, SQLite will perform an update on the row instead.
+
+```swift
+try db.run(users.upsert(email <- "alice@mac.com", name <- "Alice"), onConflictOf: email)
+// INSERT INTO "users" ("email", "name") VALUES ('alice@mac.com', 'Alice') ON CONFLICT (\"email\") DO UPDATE SET \"name\" = \"excluded\".\"name\"
+```
+
+The `upsert` function, when run successfully, returns an `Int64` representing
+the inserted row’s [`ROWID`][ROWID].
+
+```swift
+do {
+    let rowid = try db.run(users.upsert(email <- "alice@mac.com", name <- "Alice", onConflictOf: email))
+    print("inserted id: \(rowid)")
+} catch {
+    print("insertion failed: \(error)")
+}
+```
+
+The [`insert`](#inserting-rows), [`update`](#updating-rows), and [`delete`](#deleting-rows) functions
+follow similar patterns.
 
 ## Updating Rows
 

Sources/SQLite/Typed/Coding.swift

@@ -45,6 +45,29 @@ extension QueryType {
         return self.insert(encoder.setters + otherSetters)
     }
 
+
+    /// Creates an `INSERT ON CONFLICT DO UPDATE` statement, aka upsert, by encoding the given object
+    /// This method converts any custom nested types to JSON data and does not handle any sort
+    /// of object relationships. If you want to support relationships between objects you will
+    /// have to provide your own Encodable implementations that encode the correct ids.
+    ///
+    /// - Parameters:
+    ///
+    ///   - encodable: An encodable object to insert
+    ///
+    ///   - userInfo: User info to be passed to encoder
+    ///
+    ///   - otherSetters: Any other setters to include in the insert
+    ///
+    ///   - onConflictOf: The column that if conflicts should trigger an update instead of insert.
+    ///
+    /// - Returns: An `INSERT` statement fort the encodable object
+    public func upsert(_ encodable: Encodable, userInfo: [CodingUserInfoKey:Any] = [:], otherSetters: [Setter] = [], onConflictOf conflicting: Expressible) throws -> Insert {
+        let encoder = SQLiteEncoder(userInfo: userInfo)
+        try encodable.encode(to: encoder)
+        return self.upsert(encoder.setters + otherSetters, onConflictOf: conflicting)
+    }
+
     /// Creates an `UPDATE` statement by encoding the given object
     /// This method converts any custom nested types to JSON data and does not handle any sort
     /// of object relationships. If you want to support relationships between objects you will

Sources/SQLite/Typed/Query.swift

@@ -672,6 +672,45 @@ extension QueryType {
             query.expression
         ]).expression)
     }
+    
+    // MARK: UPSERT
+    
+    public func upsert(_ insertValues: Setter..., onConflictOf conflicting: Expressible) -> Insert {
+        return upsert(insertValues, onConflictOf: conflicting)
+    }
+    
+    public func upsert(_ insertValues: [Setter], onConflictOf conflicting: Expressible) -> Insert {
+        let setValues = insertValues.filter { $0.column.asSQL() != conflicting.asSQL() }
+            .map { Setter(excluded: $0.column) }
+        return upsert(insertValues, onConflictOf: conflicting, set: setValues)
+    }
+    
+    public func upsert(_ insertValues: Setter..., onConflictOf conflicting: Expressible, set setValues: [Setter]) -> Insert {
+        return upsert(insertValues, onConflictOf: conflicting, set: setValues)
+    }
+    
+    public func upsert(_ insertValues: [Setter], onConflictOf conflicting: Expressible, set setValues: [Setter]) -> Insert {
+        let insert = insertValues.reduce((columns: [Expressible](), values: [Expressible]())) { insert, setter in
+            (insert.columns + [setter.column], insert.values + [setter.value])
+        }
+        
+        let clauses: [Expressible?] = [
+            Expression<Void>(literal: "INSERT"),
+            Expression<Void>(literal: "INTO"),
+            tableName(),
+            "".wrap(insert.columns) as Expression<Void>,
+            Expression<Void>(literal: "VALUES"),
+            "".wrap(insert.values) as Expression<Void>,
+            whereClause,
+            Expression<Void>(literal: "ON CONFLICT"),
+            "".wrap(conflicting) as Expression<Void>,
+            Expression<Void>(literal: "DO UPDATE SET"),
+            ", ".join(setValues.map { $0.expression })
+        ]
+        
+        return Insert(" ".join(clauses.compactMap { $0 }).expression)
+    }
+
 
     // MARK: UPDATE
 

Sources/SQLite/Typed/Setter.swift

@@ -60,6 +60,11 @@ public struct Setter {
         self.value = Expression<V?>(value: value)
     }
 
+    init(excluded column: Expressible) {
+        let excluded = Expression<Void>("excluded")
+        self.column = column
+        self.value = ".".join([excluded, column.expression])
+    }
 }
 
 extension Setter : Expressible {

Tests/SQLiteTests/QueryTests.swift

@@ -270,6 +270,24 @@ class QueryTests : XCTestCase {
         )
     }
 
+    func test_upsert_withOnConflict_compilesInsertOrOnConflictExpression() {
+        AssertSQL(
+            "INSERT INTO \"users\" (\"email\", \"age\") VALUES ('alice@example.com', 30) ON CONFLICT (\"email\") DO UPDATE SET \"age\" = \"excluded\".\"age\"",
+            users.upsert(email <- "alice@example.com", age <- 30, onConflictOf: email)
+        )
+    }
+
+    func test_upsert_encodable() throws {
+        let emails = Table("emails")
+        let string = Expression<String>("string")
+        let value = TestCodable(int: 1, string: "2", bool: true, float: 3, double: 4, optional: nil, sub: nil)
+        let insert = try emails.upsert(value, onConflictOf: string)
+        AssertSQL(
+            "INSERT INTO \"emails\" (\"int\", \"string\", \"bool\", \"float\", \"double\") VALUES (1, '2', 1, 3.0, 4.0) ON CONFLICT (\"string\") DO UPDATE SET \"int\" = \"excluded\".\"int\", \"bool\" = \"excluded\".\"bool\", \"float\" = \"excluded\".\"float\", \"double\" = \"excluded\".\"double\"",
+            insert
+        )
+    }
+
     func test_update_compilesUpdateExpression() {
         AssertSQL(
             "UPDATE \"users\" SET \"age\" = 30, \"admin\" = 1 WHERE (\"id\" = 1)",
@@ -378,7 +396,8 @@ class QueryIntegrationTests : SQLiteTestCase {
 
     let id = Expression<Int64>("id")
     let email = Expression<String>("email")
-
+    let age = Expression<Int>("age")
+    
     override func setUp() {
         super.setUp()
 
@@ -483,6 +502,20 @@ class QueryIntegrationTests : SQLiteTestCase {
         XCTAssertEqual(1, id)
     }
 
+    func test_upsert() throws {
+        let fetchAge = { () throws -> Int? in
+            return try self.db.pluck(self.users.filter(self.email == "alice@example.com")).flatMap { $0[self.age] }
+        }
+        
+        let id = try db.run(users.upsert(email <- "alice@example.com", age <- 30, onConflictOf: email))
+        XCTAssertEqual(1, id)
+        XCTAssertEqual(30, try fetchAge())
+        
+        let nextId = try db.run(users.upsert(email <- "alice@example.com", age <- 42, onConflictOf: email))
+        XCTAssertEqual(1, nextId)
+        XCTAssertEqual(42, try fetchAge())
+    }
+    
     func test_update() {
         let changes = try! db.run(users.update(email <- "alice@example.com"))
         XCTAssertEqual(0, changes)