rename & docs

typelevel · Jul 16, 2024 · 734bab5 · 734bab5
1 parent e85218d
commit 734bab5
Show file tree

Hide file tree

Showing 13 changed files with 143 additions and 113 deletions.
diff --git a/modules/core/src/main/scala/doobie/hi/connection.scala b/modules/core/src/main/scala/doobie/hi/connection.scala
@@ -60,6 +60,9 @@ object connection {
     *
     * Errors at each step are handled and logged, with cleanups (closing the PreparedStatement/ResultSet.)
     *
+    * For usage example, see [[doobie.util.query.Query.to]] or [[doobie.util.update.Update.withUniqueGeneratedKeys]]
+    * which uses this function.
+    *
     * @param create
     *   Create the PreparedStatement, using e.g. `doobie.FC.prepareStatement`
     * @param prep
@@ -91,6 +94,7 @@ object connection {
     *
     * Errors at each step are handled and logged, with the PreparedStatement being closed at the end.
     *
+    * For usage examples, see [[doobie.util.update.Update.updateMany]] which is built on this function
     * @param create
     *   Create the PreparedStatement, using e.g. `doobie.FC.prepareStatement`
     * @param prep
@@ -174,10 +178,10 @@ object connection {
       .bracket(ps => IFC.embed(ps, prepLogged *> execAndProcessLogged))(ps => IFC.embed(ps, IFPS.close))
   }
 
-  // FIXME: test PS and RS are correctly closed when there's exec error or processing error
-
   /** Execute a PreparedStatement query and provide rows from the ResultSet in chunks
     *
+    * For usage examples, see [[doobie.util.query.Query.streamWithChunkSize]] which is implemented on top of this
+    * function.
     * @param create
     *   Create the PreparedStatement, using e.g. `doobie.FC.prepareStatement`
     * @param prep

diff --git a/modules/core/src/main/scala/doobie/hi/preparedstatement.scala b/modules/core/src/main/scala/doobie/hi/preparedstatement.scala
@@ -111,7 +111,7 @@ object preparedstatement {
 
   /** @group Execution */
   @deprecated(
-    "Consider using doobie.HC.execute{With/Without}ResultSet" +
+    "Consider using doobie.HC.executeWithoutResultSet" +
       "for logging support, or switch to executeUpdateWithUniqueGeneratedKeysUnlogged instead",
     "1.0.0-RC6"
   )
@@ -123,7 +123,7 @@ object preparedstatement {
 
   /** @group Execution */
   @deprecated(
-    "Consider using doobie.HC.execute{With/Without}ResultSet" +
+    "Consider using doobie.HC.stream" +
       "for logging support, or switch to executeUpdateWithUniqueGeneratedKeysUnlogged instead",
     "1.0.0-RC6"
   )

diff --git a/modules/core/src/main/scala/doobie/util/query.scala b/modules/core/src/main/scala/doobie/util/query.scala
@@ -10,7 +10,7 @@ import cats.data.NonEmptyList
 import doobie._
 import doobie.util.analysis.Analysis
 import doobie.util.compat.FactoryCompat
-import doobie.util.log.{Arguments, LoggingInfo}
+import doobie.util.log.{Parameters, LoggingInfo}
 import doobie.util.pos.Pos
 import doobie.free.{preparedstatement => IFPS, connection => IFC}
 import doobie.hi.{connection => IHC, preparedstatement => IHPS, resultset => IHRS}
@@ -84,7 +84,7 @@ object query {
         chunkSize = chunkSize,
         loggingInfo = LoggingInfo(
           sql = sql,
-          args = Arguments.NonBatch(Write[A].toList(a)),
+          params = Parameters.NonBatch(Write[A].toList(a)),
           label = label
         )
       )
@@ -157,7 +157,7 @@ object query {
     private def mkLoggingInfo(a: A): LoggingInfo =
       LoggingInfo(
         sql = sql,
-        args = Arguments.NonBatch(write.toList(a)),
+        params = Parameters.NonBatch(write.toList(a)),
         label = label
       )
 

diff --git a/modules/core/src/main/scala/doobie/util/update.scala b/modules/core/src/main/scala/doobie/util/update.scala
@@ -12,7 +12,7 @@ import doobie.util.analysis.Analysis
 import doobie.util.pos.Pos
 import doobie.free.{connection => IFC, preparedstatement => IFPS}
 import doobie.hi.{connection => IHC, preparedstatement => IHPS, resultset => IHRS}
-import doobie.util.log.{Arguments, LoggingInfo}
+import doobie.util.log.{Parameters, LoggingInfo}
 import fs2.Stream
 
 import scala.Predef.genericArrayOps
@@ -86,7 +86,7 @@ object update {
         IFPS.executeUpdate,
         LoggingInfo(
           sql,
-          Arguments.NonBatch(write.toList(a)),
+          Parameters.NonBatch(write.toList(a)),
           label
         )
       )
@@ -107,7 +107,7 @@ object update {
         exec = IFPS.executeBatch.map(updateCounts => updateCounts.foldLeft(0)((acc, n) => acc + (n.max(0)))),
         loggingInfo = LoggingInfo(
           sql,
-          Arguments.Batch(() => fa.toList.map(write.toList)),
+          Parameters.Batch(() => fa.toList.map(write.toList)),
           label
         )
       )
@@ -130,7 +130,7 @@ object update {
             chunkSize = chunkSize,
             loggingInfo = LoggingInfo(
               sql,
-              Arguments.Batch(() => as.toList.map(Write[A].toList)),
+              Parameters.Batch(() => as.toList.map(Write[A].toList)),
               label
             )
           )
@@ -157,7 +157,7 @@ object update {
         chunkSize = chunkSize,
         loggingInfo = LoggingInfo(
           sql = sql,
-          args = Arguments.NonBatch(Write[A].toList(a)),
+          params = Parameters.NonBatch(Write[A].toList(a)),
           label = label
         )
       )
@@ -175,7 +175,7 @@ object update {
         process = IHRS.getUnique,
         loggingInfo = LoggingInfo(
           sql,
-          Arguments.NonBatch(write.toList(a)),
+          Parameters.NonBatch(write.toList(a)),
           label
         )
       )

diff --git a/modules/core/src/test/scala-2/doobie/util/QueryLogSuitePlatform.scala b/modules/core/src/test/scala-2/doobie/util/QueryLogSuitePlatform.scala
@@ -4,7 +4,7 @@
 
 package doobie.util
 
-import doobie.util.log.{Arguments, ProcessingFailure, Success}
+import doobie.util.log.{Parameters, ProcessingFailure, Success}
 import shapeless._
 
 trait QueryLogSuitePlatform { self: QueryLogSuite =>
@@ -14,17 +14,17 @@ trait QueryLogSuitePlatform { self: QueryLogSuite =>
     val Sql = "select 1 where ? = ?"
     val Arg = 1 :: 1 :: HNil
     eventForUniqueQuery(Sql, Arg) match {
-      case Success(Sql, Arguments.NonBatch(List(1, 1)), _, _, _) => ()
-      case a                                                     => fail(s"no match: $a")
+      case Success(Sql, Parameters.NonBatch(List(1, 1)), _, _, _) => ()
+      case a                                                      => fail(s"no match: $a")
     }
   }
 
   test("[Query] n-arg processing failure") {
     val Sql = "select 1 where ? = ?"
     val Arg = 1 :: 2 :: HNil
     eventForUniqueQuery(Sql, Arg) match {
-      case ProcessingFailure(Sql, Arguments.NonBatch(List(1, 2)), _, _, _, _) => ()
-      case a                                                                  => fail(s"no match: $a")
+      case ProcessingFailure(Sql, Parameters.NonBatch(List(1, 2)), _, _, _, _) => ()
+      case a                                                                   => fail(s"no match: $a")
     }
   }
 

diff --git a/modules/core/src/test/scala-3/doobie/util/QueryLogSuitePlatform.scala b/modules/core/src/test/scala-3/doobie/util/QueryLogSuitePlatform.scala
@@ -4,7 +4,7 @@
 
 package doobie.util
 
-import doobie.util.log.{Arguments, Success, ProcessingFailure}
+import doobie.util.log.{Parameters, Success, ProcessingFailure}
 
 trait QueryLogSuitePlatform { self: QueryLogSuite =>
   import doobie.generic.auto._
@@ -13,7 +13,7 @@ trait QueryLogSuitePlatform { self: QueryLogSuite =>
     val Sql = "select 1 where ? = ?"
     val Arg = 1 *: 1 *: EmptyTuple
     eventForUniqueQuery(Sql, Arg) match {
-      case Success(Sql, Arguments.NonBatch(List(1, 1)), _, _, _) => ()
+      case Success(Sql, Parameters.NonBatch(List(1, 1)), _, _, _) => ()
       case a                                                     => fail(s"no match: $a")
     }
   }
@@ -22,7 +22,7 @@ trait QueryLogSuitePlatform { self: QueryLogSuite =>
     val Sql = "select 1 where ? = ?"
     val Arg = 1 *: 2 *: EmptyTuple
     eventForUniqueQuery(Sql, Arg) match {
-      case ProcessingFailure(Sql, Arguments.NonBatch(List(1, 2)), _, _, _, _) => ()
+      case ProcessingFailure(Sql, Parameters.NonBatch(List(1, 2)), _, _, _, _) => ()
       case a                                                                  => fail(s"no match: $a")
     }
   }

diff --git a/modules/core/src/test/scala/doobie/util/QueryLogSuite.scala b/modules/core/src/test/scala/doobie/util/QueryLogSuite.scala
@@ -8,8 +8,8 @@ import cats.syntax.all._
 import cats.effect.{IO, IOLocal}
 import doobie._
 import doobie.implicits._
-import doobie.util.log.Arguments.NonBatch
-import doobie.util.log.{Arguments, ExecFailure, LogEvent, ProcessingFailure, Success}
+import doobie.util.log.Parameters.NonBatch
+import doobie.util.log.{Parameters, ExecFailure, LogEvent, ProcessingFailure, Success}
 
 class QueryLogSuite extends munit.FunSuite with QueryLogSuitePlatform {
 
@@ -69,7 +69,7 @@ class QueryLogSuite extends munit.FunSuite with QueryLogSuitePlatform {
     )
     succEvents.foreach { succ =>
       assertEquals(succ.sql, "select 1, 2")
-      assertEquals(succ.args, NonBatch(Nil))
+      assertEquals(succ.params, NonBatch(Nil))
       assertEquals(succ.label, "unlabeled")
     }
   }
@@ -86,7 +86,7 @@ class QueryLogSuite extends munit.FunSuite with QueryLogSuitePlatform {
     )
     succEvents.foreach { succ =>
       assertEquals(succ.sql, "select ?, ?")
-      assertEquals(succ.args, NonBatch(List(1, "2")))
+      assertEquals(succ.params, NonBatch(List(1, "2")))
       assertEquals(succ.label, "mylabel")
       assert(succ.exec.toNanos > 0L)
       assert(succ.processing.toNanos > 0L)
@@ -104,7 +104,7 @@ class QueryLogSuite extends munit.FunSuite with QueryLogSuitePlatform {
       execFailureEventForCIO(q.nel)
     ).foreach { ev =>
       assertEquals(ev.sql, "select bad_column")
-      assertEquals(ev.args, Arguments.nonBatchEmpty)
+      assertEquals(ev.params, Parameters.nonBatchEmpty)
       assertEquals(ev.label, "unlabeled")
       assertEquals(ev.exec.toNanos, 0L)
       assert(ev.failure.getMessage.contains("not found"))
@@ -122,7 +122,7 @@ class QueryLogSuite extends munit.FunSuite with QueryLogSuitePlatform {
       execFailureEventForCIO(q.nel("not_int"))
     ).foreach { ev =>
       assertEquals(ev.sql, "select ? :: Int")
-      assertEquals(ev.args, NonBatch(List("not_int")))
+      assertEquals(ev.params, NonBatch(List("not_int")))
       assertEquals(ev.label, "unlabeled")
       assert(ev.exec.toNanos > 0L)
       assert(ev.failure.getMessage.contains("Data conversion error"))
@@ -140,7 +140,7 @@ class QueryLogSuite extends munit.FunSuite with QueryLogSuitePlatform {
       processFailureEventForCIO(q.nel)
     ).foreach { ev =>
       assertEquals(ev.sql, "select 'not_int'")
-      assertEquals(ev.args, Arguments.nonBatchEmpty)
+      assertEquals(ev.params, Parameters.nonBatchEmpty)
       assertEquals(ev.label, "unlabeled")
       assert(ev.exec.toNanos > 0L)
       assert(ev.failure.getMessage.contains("Data conversion error"))
@@ -153,7 +153,7 @@ class QueryLogSuite extends munit.FunSuite with QueryLogSuitePlatform {
       Query[Unit, Int](sql).stream(()).compile.toList
     )
     assertEquals(succ.sql, sql)
-    assertEquals(succ.args, NonBatch(Nil))
+    assertEquals(succ.params, NonBatch(Nil))
     assertEquals(succ.label, "unlabeled")
     assert(succ.exec.toNanos > 0L)
     assertEquals(succ.processing.toNanos, 0L)
@@ -165,7 +165,7 @@ class QueryLogSuite extends munit.FunSuite with QueryLogSuitePlatform {
       Query[Unit, Int](sql).streamWithChunkSize((), 5).compile.toList
     )
     assertEquals(succ.sql, sql)
-    assertEquals(succ.args, NonBatch(Nil))
+    assertEquals(succ.params, NonBatch(Nil))
     assertEquals(succ.label, "unlabeled")
     assert(succ.exec.toNanos > 0L)
     assertEquals(succ.processing.toNanos, 0L)
@@ -178,7 +178,7 @@ class QueryLogSuite extends munit.FunSuite with QueryLogSuitePlatform {
       execFailureEventForCIO(q0.streamWithChunkSize(1).compile.toList)
     ).foreach { ev =>
       assertEquals(ev.sql, "select bad_column")
-      assertEquals(ev.args, Arguments.nonBatchEmpty)
+      assertEquals(ev.params, Parameters.nonBatchEmpty)
       assertEquals(ev.label, "unlabeled")
       assertEquals(ev.exec.toNanos, 0L)
       assert(ev.failure.getMessage.contains("not found"))
@@ -192,7 +192,7 @@ class QueryLogSuite extends munit.FunSuite with QueryLogSuitePlatform {
       execFailureEventForCIO(q0.streamWithChunkSize("not_int", 1).compile.toList)
     ).foreach { ev =>
       assertEquals(ev.sql, "select ? :: Int")
-      assertEquals(ev.args, NonBatch(List("not_int")))
+      assertEquals(ev.params, NonBatch(List("not_int")))
       assertEquals(ev.label, "unlabeled")
       assert(ev.exec.toNanos > 0L)
       assert(ev.failure.getMessage.contains("Data conversion error"))