1.0.0-RC6

Warning: We have an issue in this release related to automatic derivation not using explicitly defined instances (See #2104). Please refrain from using this release and skip to 1.0.0-RC7 when it is out.

Query Cancellation

Query cancellation has been implemented via calling PreparedStatement#close() on fiber cancellation.

Big thanks to @TalkingFoxMid and contributions from @satorg @armanbilge @jatcwang!

Related PRs: #2079 #2088

Opt-in automatic derivation

Automatic derivation has been the (non-configurable) default in Doobie since the start. While convenient, it can lead to long compile times because Read/Write/Get/Put instances are derived every time it is needed.

For those who want shorter compile times, we have now made automatic derivation opt in!

• import doobie.implicits.* will enable automatic derivation (maintaining source compatibility to ease migration).
• import doobie.generic.auto.* to explicitly enable automatic derivation. Compared to import doobie.implicits.* this brings just the implicits/givens necessary for automatic derivation
• Instances for tuples are still automatically derived for convenience
• To switch to explicitly derived instances, change your import doobie.implicits.* to import doobie.syntax.all.* and gradually fix compile errors by deriving instances explicitly (see below):

To derive instances explicitly:

Scala 3:

case class Foo(a: String, b: Int) derives Read

Scala 2+:

case class Foo(a: String, b: Int)

object Foo {
  implicit val read: Read[Foo] = Read.derived
}

Related PRs:

• Opt in auto derivation by @guymers / @jatcwang in #1967
• Fix instance derivation by @jatcwang in #2037
• Make tuple Read/Write instances available without an import by @jatcwang in #2070

Better type-checking with JDBC vendor types (For java.time.* and more)

In previous releases, doobie typecheck only checks against the int enum returned by java.sql.ResultSetMetaData#getColumnType (java.sql.Types). However this is inadequate for two reasons:

• java.sql.Types doesn't cover many other possible database-specific types (e.g. JSON column type)
• JDBC drivers often return the wrong java.sql.Types, often due to legacy

For example, for a TIMESTAMP WITH TIME ZONE column Postgres JDBC driver will report that it has the type java.sql.Types.TIMESTAMP (surprising as java.sql.Types.TIMESTAMP_WITH_TIMEZONE exists).

PostgreSQL Data Type	getColumnType()	getColumnTypeName()
TIMESTAMP	Types.TIMESTAMP	"TIMESTAMP"
TIMESTAMP WITH TIME ZONE	Types.TIMESTAMP	"TIMESTAMPTZ"

This means by just using the result from getColumnType typechecking couldn't differentiate between a TIMESTAMP WITH TIME ZONE column vs TIMESTAMP (WITHOUT TIMEZONE) column - which has serious implications for correctness of your program if one uses the wrong column type!

Fortunately, we can see that getColumnTypeName does differentiate between the two column types.

To help improve typechecking for java.time.* types (and generally), we have made the following changes:

1. Get and Put can now specify vendor column type name

When creating a Get or Put instance, the vendor type name can now be specified so typechecking will check against it.
When constructing instances (e.g. Get.Basic.one(..)) you can pass the expected vendor type to checkedVendorType parameter, or None if you don't need or want to check against the vendor type.

2. Move java.time.* instances into database modules

java.time.* instances are moved to their database-specific modules to handle differences in databases and their drivers.

doobie module	import
doobie-postgres	doobie.postgres.implicits.*
doobie-mysql	doobie.mysql.implicits.*

For other databases that support Java 8 time types, you can continue to use import doobie.implicits.javatimedrivernative.* but there's no check against vendor type names.

3. Make doobie.implicits.javasql instances available by default

doobie.implicits.javasql has now been removed. You can safely remove any import doobie.implicits.javasql.* as these instances are now available without any import.

Related PRs:

• More precise typechecking using vendor types by @jatcwang in #2023
• Improve Java time meta experience by @guymers in #1789
• Add MySQL java.time instances by @jatcwang in #2024

Logging for streaming and updateMany queries

Query/Update which now allow queries ran through Query#stream and Update#withGeneratedKeys to be logged. As part of this work, doobie.hi.FC module also have 3 new functions: stream, executeWithResultSet and executeWithoutResultSet. Old functions that does not log (such as doobie.hi.FC.updateWithGeneratedKeys) has been deprecated and will be removed by 1.0.

Related PRs:

• Fix logging for streaming and updateMany by @jatcwang in #2064

Other notable changes

• Allow for different effects of HikariTransactor and its creation by @sideeffffect in #1939
• Split methods for HikariTransactor constructed with two effects by @jatcwang in #1961
• Add parenthesis around each expression in and/or combinator by @jatcwang in #2044
• PostgreSQL Range Types by @tomohavvk in #2008
• Remove lazy initialization of modules to fix potential initialization deadlocks by @jatcwang in #2046
• Add withLogHandler method to Transactor by @sideeffffect in #1977
• Ensure backward compatibility of Hikari Config by @sideeffffect in #1842
• Improve analysis message + Small optimizations #2091
• Deprecate non-logging/non-cancelling high-level methods #2090

Dependency updates

• Update typelevel plugin and sbt-ghpages by @jatcwang in #1952
• Update sbt-typelevel-ci-release, ... to 0.6.2 by @scala-steward in #1949
• Update postgresql to 42.7.0 by @scala-steward in #1953
• Update sbt-typelevel-ci-release, ... to 0.6.3 by @scala-steward in #1955
• Upgrade postgis to 2023.1.0 / postgres-jdbc to 42.7.1 by @jatcwang in #1962
• Update sbt to 1.9.8 by @scala-steward in #1978
• Update mdoc, sbt-mdoc to 2.5.2 by @scala-steward in #1979
• Update sbt-typelevel-ci-release, ... to 0.6.5 by @scala-steward in #1980
• Update sbt-jmh to 0.4.7 by @scala-steward in #1981
• Update cats-effect, cats-effect-testkit to 3.5.3 by @scala-steward in #1983
• Update specs2-core to 4.20.4 by @scala-steward in #1982
• Update fs2-core, fs2-io to 3.9.4 by @scala-steward in #1984
• Update specs2-core to 4.20.5 by @scala-steward in #1985
• Update refined to 0.11.1 by @scala-steward in #1988
• Update paradox-theme-generic, sbt-paradox to 0.10.6 by @scala-steward in #1987
• Update weaver-cats to 0.8.4 by @scala-steward in #1986
• Update scalatest to 3.2.18 by @scala-steward in #1993
• Update sbt-typelevel-ci-release, ... to 0.6.6 by @scala-steward in #1995
• Update munit to 1.0.0-M11 by @scala-steward in #1992
• Update sbt to 1.9.9 by @scala-steward in #1998
• Update kind-projector to 0.13.3 by @scala-steward in #1999
• Update scala-library, scala-reflect to 2.12.19 by @scala-steward in #2001
• Update sbt-typelevel-ci-release, ... to 0.6.7 by @scala-steward in #2003
• Update scala3-library to 3.3.3 by @scala-steward in #2004
• Update scala-library, scala-reflect to 2.13.13 by @scala-steward in #2002
• Update cats-effect, cats-effect-testkit to 3.5.4 by @scala-steward in #2005
• Update sbt-site to 1.6.0 by @scala-steward in #2009
• Update fs2-core, fs2-io to 3.10.2 by @scala-steward in #2014
• Update postgresql to 42.7.3 by @jatcwang in #2017
• Update paradox-theme-generic, sbt-paradox to 0.10.7 by @scala-steward in #2019
• Update munit to 1.0.0-M12 by @scala-steward in #2021
• Update sbt-typelevel-ci-release, ... to 0.7.0 by @scala-steward in #2025
• Update mysql-connector-j to 8.0.33 by @scala-steward in #2026
• Update mysql-connector-j to 8.3.0 by @scala-steward in...

1.0.0-RC5

What's New

• Add module for log4cats support for debugging purposes by @sideeffffect in #1896
• Add WeakAsync.liftIO by @armanbilge in #1910
• Expose "unlabelled" as a constant by @jatcwang in #1946

Bug fixes and improvements

• Fix typo transcator -> transactor by @ag91 in #1931
• Fix NPE in Scala 3 derivation for Write by @jacektomaszek in #1890
• Fix future leak by @TimWSpence in #1951
• Use syncStep in WeakAsync.liftK by @armanbilge in #1906
• Fix fragment helpers to handle fragments without spaces at the end (i.e. fr0, sql interpolator) by @jatcwang in #1912
• Generate return types for KleisliInterpreter methods by @jatcwang in #1929

New Contributors

• @jacektomaszek made their first contribution in #1890
• @albertpastrana made their first contribution in #1897
• @arturaz made their first contribution in #1907
• @Daenyth made their first contribution in #1928
• @ag91 made their first contribution in #1931
• @felix-hedenstrom made their first contribution in #1937
• @BenMotz made their first contribution in #1948
• @jrozanski made their first contribution in #1950

Full Changelog: v1.0.0-RC4...v1.0.0-RC5

v1.0.0-RC4

• Revert slf4j to 1.7.36. See #1885 #1883

v1.0.0-RC3

Java 11 & major dependency updates

• The minimum Java version is now 11
• slf4j version is now 2.x (In order to update to latest HikariCP)
• Depends on cats-effect 3.5 & fs2 3.7

Effectful Logging & Transactor-level logging

In previous versions Doobie supports SQL statement logging via LogHandler. However, it has the slightly awkward interface of final case class LogHandler(unsafeRun: LogEvent => Unit) which makes it difficult to integrate with pure FP logging libraries.

We have reworked how logging works, with the two major difference being:

• LogHandler now runs in an effect i.e. def run(logEvent: LogEvent): M[Unit]
• Each Transactor[M] now has a single LogHandler[M] attached to it, in order to align the effect type.

To recover some of the previous functionality of per-query logging logic, you can call .queryWithLabel/.updateWithLabel (instead of .query/.update) to attach a String label to each query.
This label will be set for each LogEvent, which your LogHandler can then use to differentiate the queries being logged. (e.g. use it for metrics)

For more advanced use case where you want to pass more structured contextual information for logging purposes, you can use IOLocal (The docs on logging has an example)

Big thanks to @oyvindberg for the implementation of effectful LogHandler and @george-wilson-rea for adding query labels

Basic migration steps

• Add a LogHandler[M] when constructing your Transactor (or pass a None if you don't want to log events)
• Replace queryWithLogHandler/updateWithLogHandler with queryWithLabel/updateWithLabel

Tightening Postgres java.time instance typecheck

In #1735 / #1736, we tightened Meta instances for PostgreSQL java.time instances to reflect what the postgres-jdbc driver actually allows. For example, typechecking a query that tries to map a java.time.OffsetDateTime to a VARCHAR column in the database will now fail.

Instance for ZonedDateTime has also been removed as it is misleading (PostgreSQL does not support a timestamp type that stores the timezone)

All PostgreSQL users should migrate to using doobie.postgres.JavaTimeInstances which has stricter type-checking to help you catch errors. For example, it enforces that the corresponding column type of an java.time.Instant must be TIMESTAMP WITH TIME ZONE.

Thanks @guymers!

doobie-hikari: Now automatically creates the Connect ExecutionContext

doobie.hikari.HikariTransactor#fromConfig/fromHikariConfig previously requires you to pass in a connectEC: ExecutionContext parameter used when awaiting a connection from the hikari connection pool.
Since the general best practice is to set this fixed-size pool to your hikari connection pool size, we now automatically create this ExecutionContext for you based on hikariConfig.getMaximumPoolSize.

If you want to use your own connectEC like previous versions, you can use doobie.hikari.HikariTransactor#fromConfigCustomEC/fromHikariConfigCustomEC instead.

By @sideeffffect in #1690 and #1745

Improved composability and safety of fragment helpers (doobie.util.fragments.*)

• when calling methods like and/or, we now wrap the resulting expression in parenthesis.
  This prevents scenarios where the boolean logic generated by and/or can be influenced by its surroundings due to the lack of parenthesis

For example, previously the code fr"cond1 AND ${or(cond2, cond3)}" evaluates to the SQL cond1 AND cond2 OR cond3, which is most likely not equivalent to the user's intention of cond1 AND (cond2 OR cond3) and will behave differently for certain cond1/2/3 values.

Basic migration steps

• Fix compile errors from andOpt/orOpt, which now return an Option[Fragment].
• Carefully check use of and/or/andOpt/orOpt if they are used in conjunction with other AND/OR. If you were previously relying on fragment helpers NOT wrapping the resulting expression in parenthesis, you should adjust your code to maintain to old behaviour**

Other additions

• Add Semigroup and Monoid instances for ConnectionIO and friends by @Fristi in #1729
• Add weaver test framework integration by @danielkarch in #1668
• Added doobie.hikari.HikariTransactor.fromConfigAutoEc which automatically creates/configures the ExecutionContext which awaits connections from the pool, following best practices. By @sideeffffect in #1690

Binary Compatibility

v1.0.0-RC3 is NOT binary compatible

v1.0.0-RC2

New

• Enable support for derives in Scala 3 for Read, Write and Text (#1594 by @oyvindberg)
• Add support for JSON in H2 using circe (#1599 by @andrzejressel)
• Add Config case class (#1541 by @sideeffffect). This allow you to more easily configure Hikari connection pool settings using libraries like Pureconfig that relies on derivation.
• Add a cause to the munit Checker failure (#1564 by @brendanmaguire)

Fixes

• Fix effectful copyIn (#1512 by @oyvindberg)
• Fix name of the implicit val defining the function for the Get and Write types (#1598 by @rcardin)
• Various doc fixes thanks to @andrzejressel, @LazyBun, @jatcwang, @mbablok

Removed

• Remove Quill integration (doobie-quill) #1587

v1.0.0-RC1

This is the first 1.0.0 release candidate, built on Cats-Effect 3 on the main branch.

v0.13.4

v0.13.4 (For cats-effect 2)

Scala 3.0.0 support

Doobie is now published for Scala 3.0.0!

New integration with MUnit (doobie-munit)

Doobie now integrates with the https://scalameta.org/munit test framework via the doobie-munit module.

See https://tpolecat.github.io/doobie/docs/13-Unit-Testing.html on how to use it!

Big thanks to @Kazark and @alejandrohdezma for contributing this integration!

v1.0.0-M2

Support for Scala 3 RC3, Drops RC1. (Note that Doobie 1.x integrates with cats-effect 3.x)

v0.13.1

Now published for Scala 3 RC3

v0.12.1

The previous version (v0.12.0) upgraded Hikari to v4, which pulls in slf4j v2, which is incompatible with the version most people are using. So this version reverts that upgrade. No other changes.