v1.0.0-RC7
[!IMPORTANT]
When upgrading, please skip 1.0.0-RC6. It is considered a broken release due to issues with unexpected implicit prioritization, which we've fixed in RC7. Apologies to those that updated RC6 when it first came out!
Release notes below include all changes since 1.0.0-RC5.
Notable features / changes
Query Cancellation
Query cancellation has been implemented via calling PreparedStatement#close() on fiber cancellation.
Big thanks to @TalkingFoxMid and contributions from @satorg @armanbilge!
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.
We have significantly reworked the internals of Read/Write derivation to allow opt-in semi-auto and automatic derivation.
import doobie.implicits.*will enable automatic derivation (maintaining source compatibility to ease migration).import doobie.generic.auto.*to explicitly enable automatic derivation. Compared toimport 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
import doobie.implicits.*toimport 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
[!IMPORTANT]
For Scala 3, we highly recommend using explicit derivation and avoid any automatic derivation (i.e. no imports ofdoobie.implicits.*orimport doobie.generic.auto.*). Scala 3's implicit search algorithm doesn't seem to follow implicit prioritization the same way as Scala 2 compile, which means its implicit search is very expensive with automatic derivation (Leading to long compile times and "Implicit search problem too large." error for bigger case classes). See #2214 for more information.
Scala 2+:
case class Foo(a: String, b: Int)
object Foo {
implicit val read: Read[Foo] = Read.derived
}
As part of this derivatino rework, it is now possible to obtain a Read[Option[A]]/Write[Option[A]] instance
directly from Read[A]/Write[A].
Related PRs:
- Opt in auto derivation by @guymers / @jatcwang in https://github.com/tpolecat/doobie/pull/1967
- Rework Read/Write & Fix derivation to use custom instances by @jatcwang in https://github.com/typelevel/doobie/pull/2136
- Fix instance derivation by @jatcwang in https://github.com/tpolecat/doobie/pull/2037
- Make tuple Read/Write instances available without an import by @jatcwang in https://github.com/tpolecat/doobie/pull/2070
Better type-checking with JDBC vendor types (For Postgres java.time.* and enums)
In previous releases, doobie typecheck only checks against the integer (enum) returned by java.sql.ResultSetMetaData#getColumnType (java.sql.Types). However this is inadequate for two reasons:
java.sql.Typesdoesn't cover many other possible database-specific types (e.g. JSON column type)- JDBC drivers often return the wrong
java.sql.Typesfor legacy reasons
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.
4. Better typechecked array enum columns (Postgres-only)
If you have a column which is an array of enum type, you should switch to use doobie.postgres.implicits.arrayOfEnum
to define the Meta instance on the application side for better typechecking.
Related PRs:
- More precise typechecking using vendor types by @jatcwang in https://github.com/tpolecat/doobie/pull/2023
- Improve Java time meta experience by @guymers in https://github.com/tpolecat/doobie/pull/1789
- Add MySQL java.time instances by @jatcwang in https://github.com/tpolecat/doobie/pull/2024
- Better postgres array of enum support by @jatcwang in https://github.com/typelevel/doobie/pull/2179
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 https://github.com/tpolecat/doobie/pull/2064
Other changes
- Allow for different effects of HikariTransactor and its creation by @sideeffffect in https://github.com/tpolecat/doobie/pull/1939
- Split methods for HikariTransactor constructed with two effects by @jatcwang in https://github.com/tpolecat/doobie/pull/1961
- Add parenthesis around each expression in and/or combinator by @jatcwang in https://github.com/tpolecat/doobie/pull/2044
- PostgreSQL Range Types by @tomohavvk in https://github.com/tpolecat/doobie/pull/2008
- Remove lazy initialization of modules to fix potential initialization deadlocks by @jatcwang in https://github.com/tpolecat/doobie/pull/2046
- Add withLogHandler method to Transactor by @sideeffffect in https://github.com/tpolecat/doobie/pull/1977
- Ensure backward compatibility of Hikari Config by @sideeffffect in https://github.com/tpolecat/doobie/pull/1842
- Improve analysis message + Small optimizations https://github.com/typelevel/doobie/pull/2091
- Deprecate non-logging/non-cancelling high-level methods https://github.com/typelevel/doobie/pull/2090
- Introduce
updateSetOptfragment (#1893) by @matsluni in https://github.com/typelevel/doobie/pull/2126 - Add
INandNOT INfragment builders for product types with arbitrary arities by @satorg in https://github.com/typelevel/doobie/pull/2128 - Fragment concat operator that ensures a whitespace in between https://github.com/typelevel/doobie/pull/2166
- Prefetch a chunk of result for stream operation by @wb14123 in https://github.com/typelevel/doobie/pull/2137
- Make null param error more informative (#809) by @ulfryk in https://github.com/typelevel/doobie/pull/2142
Notable dependency updates
- Update munit to 1.1.0 by @jatcwang in https://github.com/typelevel/doobie/pull/2184
- Update mysql-connector-j to 9.2.0 by @scala-steward in https://github.com/typelevel/doobie/pull/2174
- Update HikariCP to 6.2.1 by @scala-steward in https://github.com/typelevel/doobie/pull/2145
- Update cats-effect, cats-effect-testkit to 3.5.7 by @scala-steward in https://github.com/typelevel/doobie/pull/2153
Internal/doc changes
- Make freeGen2 run manually (but verified by CI) by @jatcwang in https://github.com/tpolecat/doobie/pull/1960
- Cleanup some imports by @jatcwang in https://github.com/tpolecat/doobie/pull/1966
- Cleanup compile warnings in Scala 2 by @jatcwang in https://github.com/tpolecat/doobie/pull/1969
- Xsource:3 and convert code to be more "Scala 3" by @jatcwang in https://github.com/tpolecat/doobie/pull/2066
- Add source:future / better-monaidic-for for irrefutable pattern in for comprehension by @jatcwang in https://github.com/tpolecat/doobie/pull/2069
- docs: related projects by @arturaz in https://github.com/tpolecat/doobie/pull/2071
- [Doc] Explain the F and C in doobie.FC/HC by @jatcwang in https://github.com/tpolecat/doobie/pull/2047
- Small comments for better explanation by @jatcwang in https://github.com/tpolecat/doobie/pull/2038
- expand on hikari example by @jatcwang in https://github.com/tpolecat/doobie/pull/2013
- Add 'scalafmt' to the project by @satorg in https://github.com/tpolecat/doobie/pull/1989
- Make docker build run on Applie Silicone #2149 by @alstepan in https://github.com/typelevel/doobie/pull/2151
- fix typo by @lambdista in https://github.com/typelevel/doobie/pull/2119
- Contributing.md - add Apple silicone instructions by @jatcwang in https://github.com/typelevel/doobie/pull/2155
- Contriuting.md - document turning on and off strict mode by @jatcwang in https://github.com/typelevel/doobie/pull/2156
- Fix docs and check makeSite passes in CI by @jatcwang in https://github.com/typelevel/doobie/pull/2160
- More tests to verify derived instances by @jatcwang in https://github.com/typelevel/doobie/pull/2138
- Benchmark for Read performance by @jatcwang in https://github.com/typelevel/doobie/pull/2139
- Add mention of otel4s-doobie to docs (related projects) by @arturaz in https://github.com/typelevel/doobie/pull/2178
- Add test for Read handling of nested Optional values #2144 by @david-lebl-adastra in https://github.com/typelevel/doobie/pull/2180
- Using Munit Cats Effects for some test suites by @jf-botto in https://github.com/typelevel/doobie/pull/2181
- Simplify / optimize QueryLogSuite by @jatcwang in https://github.com/typelevel/doobie/pull/2182
- Reduce MinSuccessfulTests to reduce some test suites' execution time by @jatcwang in https://github.com/typelevel/doobie/pull/2185
- Fix outdated comments by @matsluni in https://github.com/typelevel/doobie/pull/2105
New Contributors
- @tomohavvk made their first contribution in https://github.com/tpolecat/doobie/pull/2008
- @satorg made their first contribution in https://github.com/tpolecat/doobie/pull/1989
- @matsluni made their first contribution in https://github.com/typelevel/doobie/pull/2105
- @lambdista made their first contribution in https://github.com/typelevel/doobie/pull/2119
- @wb14123 made their first contribution in https://github.com/typelevel/doobie/pull/2137
- @ulfryk made their first contribution in https://github.com/typelevel/doobie/pull/2142
- @alstepan made their first contribution in https://github.com/typelevel/doobie/pull/2151
- @david-lebl-adastra made their first contribution in https://github.com/typelevel/doobie/pull/2180
- @jf-botto made their first contribution in https://github.com/typelevel/doobie/pull/2181
Big thanks to all new and regular contributors!
Full Changelog: https://github.com/typelevel/doobie/compare/v1.0.0-RC5...v1.0.0-RC7