Implement .getGeneratedKeys[R] (#9)

I hardcoded it into the base `DbApi`/`Query` APIs, rather than as a
dialect. Sqlite doesn't support it, but it is a builtin part of the JDBC
interface, so it's a bit on the fence which side it should go. But the
fact that it does need special support in the core `DbApi`
implementation makes me lean towards treating it as a builtin

We need to pass an explicit `[R]` type parameter to `.getGeneratedKeys`
because our `Table` model is not rich enough to tell us what the auto
generated primary keys of the table are. This is in contrast to richer
models like SLICK which do contain this information. We can streamline
this later if necessary, but passing in `[Int]` or whatever is not a
huge hardship.

docs/reference.md

@@ -139,6 +139,38 @@ dbClient.transaction { db =>
 
 
 
+### DbApi.updateGetGeneratedKeysSql
+
+Allows you to fetch the primary keys that were auto-generated for an INSERT
+defined as a `SqlStr`.
+Note: not supported by Sqlite https://github.com/xerial/sqlite-jdbc/issues/980
+
+```scala
+dbClient.transaction { db =>
+  val newName = "Moo Moo Cow"
+  val newDateOfBirth = LocalDate.parse("2000-01-01")
+  val generatedIds = db
+    .updateGetGeneratedKeysSql[Int](
+      sql"INSERT INTO buyer (name, date_of_birth) VALUES ($newName, $newDateOfBirth), ($newName, $newDateOfBirth)"
+    )
+
+  assert(generatedIds == Seq(4, 5))
+
+  db.run(Buyer.select) ==> List(
+    Buyer[Sc](1, "James Bond", LocalDate.parse("2001-02-03")),
+    Buyer[Sc](2, "叉烧包", LocalDate.parse("1923-11-12")),
+    Buyer[Sc](3, "Li Haoyi", LocalDate.parse("1965-08-09")),
+    Buyer[Sc](4, "Moo Moo Cow", LocalDate.parse("2000-01-01")),
+    Buyer[Sc](5, "Moo Moo Cow", LocalDate.parse("2000-01-01"))
+  )
+}
+```
+
+
+
+
+
+
 ### DbApi.runRaw
 
 `runRawQuery` is similar to `runQuery` but allows you to pass in the SQL strings
@@ -183,6 +215,40 @@ dbClient.transaction { db =>
 
 
 
+### DbApi.updateGetGeneratedKeysRaw
+
+Allows you to fetch the primary keys that were auto-generated for an INSERT
+defined using a raw `java.lang.String` and variables.
+Note: not supported by Sqlite https://github.com/xerial/sqlite-jdbc/issues/980
+
+```scala
+dbClient.transaction { db =>
+  val generatedKeys = db.updateGetGeneratedKeysRaw[Int](
+    "INSERT INTO buyer (name, date_of_birth) VALUES (?, ?), (?, ?)",
+    Seq(
+      "Moo Moo Cow",
+      LocalDate.parse("2000-01-01"),
+      "Moo Moo Cow",
+      LocalDate.parse("2000-01-01")
+    )
+  )
+  assert(generatedKeys == Seq(4, 5))
+
+  db.run(Buyer.select) ==> List(
+    Buyer[Sc](1, "James Bond", LocalDate.parse("2001-02-03")),
+    Buyer[Sc](2, "叉烧包", LocalDate.parse("1923-11-12")),
+    Buyer[Sc](3, "Li Haoyi", LocalDate.parse("1965-08-09")),
+    Buyer[Sc](4, "Moo Moo Cow", LocalDate.parse("2000-01-01")),
+    Buyer[Sc](5, "Moo Moo Cow", LocalDate.parse("2000-01-01"))
+  )
+}
+```
+
+
+
+
+
+
 ### DbApi.stream
 
 `db.stream` can be run on queries that return `Seq[T]`s, and makes them
@@ -5877,6 +5943,262 @@ Purchase.select.mapAggregate((p, ps) =>
 
 
 
+## GetGeneratedKeys
+`INSERT` operations with `.getGeneratedKeys`. Not supported by Sqlite (see https://github.com/xerial/sqlite-jdbc/issues/980)
+### GetGeneratedKeys.single.values
+
+`getGeneratedKeys` on an `insert` returns the primary key, even if it was provided
+ explicitly.
+
+```scala
+Buyer.insert
+  .values(
+    Buyer[Sc](17, "test buyer", LocalDate.parse("2023-09-09"))
+  )
+  .getGeneratedKeys[Int]
+```
+
+
+*
+    ```sql
+    INSERT INTO buyer (id, name, date_of_birth) VALUES (?, ?, ?)
+    ```
+
+
+
+*
+    ```scala
+    Seq(17)
+    ```
+
+
+
+----
+
+
+
+```scala
+Buyer.select.filter(_.name `=` "test buyer")
+```
+
+
+
+
+*
+    ```scala
+    Seq(Buyer[Sc](17, "test buyer", LocalDate.parse("2023-09-09")))
+    ```
+
+
+
+### GetGeneratedKeys.single.columns
+
+All styles of `INSERT` query support `.getGeneratedKeys`, with this example
+using `insert.columns` rather than `insert.values`. You can also retrieve
+the generated primary keys using any compatible type, here shown using `Long`
+rather than `Int`
+
+```scala
+Buyer.insert
+  .columns(
+    _.name := "test buyer",
+    _.dateOfBirth := LocalDate.parse("2023-09-09"),
+    _.id := 4
+  )
+  .getGeneratedKeys[Long]
+```
+
+
+*
+    ```sql
+    INSERT INTO buyer (name, date_of_birth, id) VALUES (?, ?, ?)
+    ```
+
+
+
+*
+    ```scala
+    Seq(4L)
+    ```
+
+
+
+----
+
+
+
+```scala
+Buyer.select.filter(_.name `=` "test buyer")
+```
+
+
+
+
+*
+    ```scala
+    Seq(Buyer[Sc](4, "test buyer", LocalDate.parse("2023-09-09")))
+    ```
+
+
+
+### GetGeneratedKeys.single.partial
+
+If the primary key was not provided but was auto-generated by the database,
+`getGeneratedKeys` returns the generated value
+
+```scala
+Buyer.insert
+  .columns(_.name := "test buyer", _.dateOfBirth := LocalDate.parse("2023-09-09"))
+  .getGeneratedKeys[Int]
+```
+
+
+*
+    ```sql
+    INSERT INTO buyer (name, date_of_birth) VALUES (?, ?)
+    ```
+
+
+
+*
+    ```scala
+    Seq(4)
+    ```
+
+
+
+----
+
+
+
+```scala
+Buyer.select.filter(_.name `=` "test buyer")
+```
+
+
+
+
+*
+    ```scala
+    Seq(Buyer[Sc](4, "test buyer", LocalDate.parse("2023-09-09")))
+    ```
+
+
+
+### GetGeneratedKeys.batch.partial
+
+`getGeneratedKeys` can return multiple generated primary key values for
+a batch insert statement
+
+```scala
+Buyer.insert
+  .batched(_.name, _.dateOfBirth)(
+    ("test buyer A", LocalDate.parse("2001-04-07")),
+    ("test buyer B", LocalDate.parse("2002-05-08")),
+    ("test buyer C", LocalDate.parse("2003-06-09"))
+  )
+  .getGeneratedKeys[Int]
+```
+
+
+*
+    ```sql
+    INSERT INTO buyer (name, date_of_birth)
+    VALUES (?, ?), (?, ?), (?, ?)
+    ```
+
+
+
+*
+    ```scala
+    Seq(4, 5, 6)
+    ```
+
+
+
+----
+
+
+
+```scala
+Buyer.select
+```
+
+
+
+
+*
+    ```scala
+    Seq(
+      Buyer[Sc](1, "James Bond", LocalDate.parse("2001-02-03")),
+      Buyer[Sc](2, "叉烧包", LocalDate.parse("1923-11-12")),
+      Buyer[Sc](3, "Li Haoyi", LocalDate.parse("1965-08-09")),
+      // id=4,5,6 comes from auto increment
+      Buyer[Sc](4, "test buyer A", LocalDate.parse("2001-04-07")),
+      Buyer[Sc](5, "test buyer B", LocalDate.parse("2002-05-08")),
+      Buyer[Sc](6, "test buyer C", LocalDate.parse("2003-06-09"))
+    )
+    ```
+
+
+
+### GetGeneratedKeys.select.simple
+
+`getGeneratedKeys` can return multiple generated primary key values for
+an `insert` based on a `select`
+
+```scala
+Buyer.insert
+  .select(
+    x => (x.name, x.dateOfBirth),
+    Buyer.select.map(x => (x.name, x.dateOfBirth)).filter(_._1 <> "Li Haoyi")
+  )
+  .getGeneratedKeys[Int]
+```
+
+
+*
+    ```sql
+    INSERT INTO buyer (name, date_of_birth)
+    SELECT buyer0.name AS res_0, buyer0.date_of_birth AS res_1
+    FROM buyer buyer0
+    WHERE (buyer0.name <> ?)
+    ```
+
+
+
+*
+    ```scala
+    Seq(4, 5)
+    ```
+
+
+
+----
+
+
+
+```scala
+Buyer.select
+```
+
+
+
+
+*
+    ```scala
+    Seq(
+      Buyer[Sc](1, "James Bond", LocalDate.parse("2001-02-03")),
+      Buyer[Sc](2, "叉烧包", LocalDate.parse("1923-11-12")),
+      Buyer[Sc](3, "Li Haoyi", LocalDate.parse("1965-08-09")),
+      // id=4,5 comes from auto increment, 6 is filtered out in the select
+      Buyer[Sc](4, "James Bond", LocalDate.parse("2001-02-03")),
+      Buyer[Sc](5, "叉烧包", LocalDate.parse("1923-11-12"))
+    )
+    ```
+
+
+
 ## SubQuery
 Queries that explicitly use subqueries (e.g. for `JOIN`s) or require subqueries to preserve the Scala semantics of the various operators
 ### SubQuery.sortTakeJoin

mill

@@ -7,7 +7,7 @@
 set -e
 
 if [ -z "${DEFAULT_MILL_VERSION}" ] ; then
-  DEFAULT_MILL_VERSION=0.11.6
+  DEFAULT_MILL_VERSION=0.11.7-29-f2e220
 fi
 
 if [ -z "$MILL_VERSION" ] ; then