update-docs

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