Adds multirow insert method

[NeedleInAJayStack]

These changes are now available in 3.32.0

This adds functionality to do a multi-row inserts with a single values method call.

Previously, to insert multiple rows a user had to call values repeatedly:

db.insert(into: "planets")
    .columns(["name", "color"])
    .values([SQLBind("Jupiter"), SQLBind("orange")])
    .values([SQLBind("Mars"), SQLBind("red")])
    .run()

This was a bit awkward when inserting rows from an array, where an instance of the builder had to be saved off and edited:

let rows: [[SQLExpression]]  = [[...], [...], ...]
let builder = db.insert(into: "planets")
    .columns(["name", "color"])
for row in rows {
    builder.values(row)
}
builder.run()

This MR simplifies the mutli-row insert situation by adding a values method overload that accepts a nested array:

db.insert(into: "planets")
    .columns(["name", "color"])
    .values([[SQLBind("Jupiter"), SQLBind("orange")], [SQLBind("Mars"), SQLBind("red")]])
    .run()

let rows  = [[...], [...], ...]
db.insert(into: "planets")
    .columns(["name", "color"])
    .values(rows)
    .run()

NOTE

This functionality was only added to the SQLExpression version of values, NOT the Encodable version of values. There are known issues with [Encodable] conforming to Encodable that prevent adequate type checks.

For example, if a values(_ rows: [[Encodable]]) is defined, it is undeterministic since the same call would also match values(_ rows: [Encodable]). If instead we change values(_ rows: [Encodable]) to detect [[Encodable]] cases at runtime, then it is difficult to guarantee that a caller hasn't mixed Encodable and [Encodable] values.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (3c8c6aa) to head (e2b955b).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #153   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          100       100           
  Lines         2635      2636    +1     
=========================================
+ Hits          2635      2636    +1     

Files with missing lines	Coverage Δ
...it/Builders/Implementations/SQLInsertBuilder.swift	100.00% <100.00%> (ø)

[gwynne]

I've been meaning to upstream basically this exact helper myself! 🙂 I have two nits:

1. I'd rather it not be just another overload of values(_:), but have a unique name - consider an attempt to insert into a table with a single column of array type. I named my version multiValues(_:), but I'm not at all convinced that's an ideal name either and would actually welcome a bit of bikeshedding on the matter.
2. My implementation is a bit more generic:

   extension SQLInsertBuilder {
       @discardableResult
       public func multiValues<S1, S2>(_ valueSets: S1) -> Self
           where S1: Sequence, S2: Sequence,
                 S1.Element == S2, S2.Element == SQLExpression
       {
           valueSets.reduce(self) { $0.values(Array($1)) }
       }
   }

   Even though the input gets converted back to Array in the end regardless, accepting generic sequences allows for cleaner syntax when using, for example, the methods from swift-algorithms to process the data to be inserted.

[NeedleInAJayStack]

welcome a bit of bikeshedding on the matter

I think multiValues(_:) is a fine name. Along the same vein, allValues seems like a reasonable option. However, I think I prefer rows(_:) or rowValues(_:), since I feel like they imply that all sequences should have equal length and correspond to the column ordering.

[NeedleInAJayStack]

@gwynne Sorry it took so long to get back to this one. I've adjusted it to use your implementation (which is great!), and named it rows. Again, I'm happy to switch to multiValues if you prefer that. Thanks!

[gwynne]

@NeedleInAJayStack Any chance you'd be able to update this to resolve the conflicts? I'd be willing to merge it as SQLKit 3's last new feature.

[NeedleInAJayStack]

Sure, I can have that done in the next day or so if that works

[NeedleInAJayStack]

Hey @gwynne, I've resolved the merge conflicts and updated the tests to the new test formatting. I wasn't sure if any of the tests in the original PR were obsoleted by new work, so just let me know if you'd like any removed/organized differently. Thanks!

[gwynne]

Nope, everything looks fine, thanks for your work on this!