typelevel/doobie

This system is a functional database interaction library for Scala that provides a type-safe, effect-based API for executing SQL queries and managing database connections. It supports multiple databases including PostgreSQL, MySQL, and H2, offering features such as automatic type derivation, streaming data transfers, and integration with modern Scala testing frameworks. The library is built on Cats Effect and FS2, ensuring consistent asynchronous handling and resource management across different effect types.

23 changes.

This period focused on modernizing the codebase by removing legacy database abstraction types and migrating to Cats Effect 3 and Scala 3. The work included upgrading build infrastructure, introducing automatic typeclass derivation, and expanding support for PostgreSQL and H2 with new high-level APIs and streaming capabilities.

21 changes.

This period focused on expanding PostgreSQL capabilities with Circe JSON/JSONB support and comprehensive enum handling, while simultaneously migrating the codebase to support Scala 3. Significant infrastructure work included introducing a WeakAsync typeclass for uniform effect handling and building a new logging and tracing subsystem. Extensive test coverage was added across core, Hikari, and PostgreSQL modules to ensure stability for these new features and platform-specific derivations.

19 changes.

This period focused on expanding Doobie's ecosystem by adding integration modules for MUnit, Weaver, and OpenTelemetry to enhance testing and observability. It also introduced support for new database features, including JSON columns in H2 and PostgreSQL, PostgreSQL range types, and Java 8 date/time mappings for MySQL.

The \postgres-circe\ module now provides Doobie type classes (\Put\/\Get\) for circe \Json\ types, enabling seamless storage and retrieval of JSON and JSONB columns in PostgreSQL. This includes support for single values and arrays (\Array\[Json\]\), with instances organized into \json\ and \jsonb\ packages for explicit import.

modules/postgres-circe/src/main · high confidence

This change introduces the H2 database module, providing the necessary type class instances and utilities to use H2 with Doobie. It includes \H2Transactor\ for creating connection resources, specific \Meta\ instances for Java 8 time types (such as \LocalDate\, \LocalDateTime\, \Instant\) and \UUID\, as well as comprehensive support for reading and writing primitive and boxed array types (Boolean, Integer, Long, Float, Double, String).

modules/h2/src/main · high confidence

The \modules/munit\ module now provides MUnit-based testing utilities for doobie, allowing users to integrate query analysis checks directly into their MUnit test suites. The new \Checker\ and \IOChecker\ traits enable assertions on \Query\ and \Query0\ values to verify their SQL structure and output analysis, with failures including specific error items for easier debugging. This replaces or supplements previous testing approaches by conforming to the MUnit framework while maintaining compatibility with doobie's analysis capabilities.

modules/munit/src/main · high confidence

A new PosPlatform trait is introduced in the Scala 2 specific source directory, providing an implicit Pos instance via a macro. This enables automatic capture of source file and line information for debugging or logging within the doobie library on Scala 2 platforms.

modules/free/src/main/scala-2 · high confidence

The Scala 2-specific module for the Postgres backend now includes a new \TextPlatform\ trait that provides implicit conversions for handling HLists (including single-element and multi-element lists) and generic types via Shapeless. This implementation enables the \Text\ typeclass to work with complex nested structures and case classes in Scala 2, leveraging Shapeless's \Generic\ and \HList\ capabilities for automatic derivation.

modules/postgres/src/main/scala-2 · high confidence

A new PosPlatform trait and implementation have been added to the Scala 3 module, providing an implicit Pos instance that uses a macro to capture the source file path and line number of the macro expansion at compile time. This enables doobie to automatically track the origin of SQL statements in Scala 3 projects without requiring manual position arguments.

modules/free/src/main/scala-3 · high confidence

A new \Log4CatsDebuggingLogHandler\ is now available in the \org.typelevel.doobie.log4cats\ package, allowing users to log detailed SQL execution information (including statements, parameters, and timing) via log4cats. This handler is intended for debugging purposes only and should not be used in production as it may expose sensitive data.

modules/log4cats · high confidence

The specs2 module now provides \AnalysisMatchers\ and \AnalysisSpec\ traits, allowing users to verify the type-checking and analysis results of doobie \Query\ and \Update\ values directly within specs2 specifications. This enables assertions like \sql"select 1".query\[Int\] must typecheck\ or using the \check\ method to validate query structures against the database schema.

modules/specs2/src/main · high confidence

Users can now store and retrieve JSON data in H2 databases using circe's Json type. This change introduces new implicit instances that map circe Json objects to and from database columns (stored as VARCHAR/JSON), and provides helper methods to encode/decode arbitrary case classes directly to/from JSON columns in H2.

modules/h2-circe/src/main · high confidence

The MySQL module now includes built-in support for mapping Java 8 \java.time\ types (such as \Instant\, \LocalDate\, \LocalDateTime\, \LocalTime\, and \OffsetDateTime\) to corresponding MySQL database columns. These mappings are provided via the \MysqlJavaTimeInstances\ trait and are automatically available through the \org.typelevel.doobie.mysql.implicits\ package object, allowing users to read and write these types without manual configuration. Comprehensive tests verify the correctness of these mappings for both read and write operations.

modules/mysql · high confidence

This change introduces a new \Range\ type within the \org.typelevel.doobie.postgres.types\ package to handle PostgreSQL range data. It provides a sealed trait hierarchy (\EmptyRange\ and \NonEmptyRange\) that models range boundaries with inclusive or exclusive edges (e.g., \\[a, b)\). The implementation includes utility methods for encoding Scala range objects into PostgreSQL string formats and decoding incoming strings back into typed Scala values, along with equality instances for the edge types.

modules/postgres/src/main/scala/doobie/postgres/types · high confidence

This change introduces new implicit instances in the \org.typelevel.doobie.refined\ package that enable seamless integration with the \eu.timepit.refined\ library. Users can now use refined types (e.g., \Refined\[Int, Positive\]\) directly in doobie queries, where values are automatically validated upon reading from the database and unwrapped when writing to it. The implementation handles validation failures by throwing a \SecondaryValidationFailed\ exception, ensuring that invalid data does not silently enter the application domain.

modules/refined/src/main · high confidence

New SQL initialization files have been added to the \init\ directory to support database setup for testing. The MySQL script (\init/mysql/test-table.sql\) creates a test table with various data types and inserts sample data. The PostgreSQL script (\init/postgres/test-db.sql\) sets up a more extensive schema including PostGIS and hstore extensions, custom enum types, and a large dataset of city and country records based on the world database sample.

init · high confidence

The Postgres module now supports Scala 3's \derives\ mechanism for the \Text\ typeclass, allowing automatic generation of text formatting instances for case classes (products) and tuples. This change introduces new given instances in \TextPlatform.scala\ that leverage Scala 3's \Mirror\ API to handle single-element tuples, multi-element tuples, and product types, reducing the need for manual \Text\ definitions for these data structures.

modules/postgres/src/main/scala-3 · high confidence

This release significantly expands the PostgreSQL module with new type mappings and utilities. It adds support for Java 8 time types (OffsetDateTime, LocalDate, LocalTime, LocalDateTime, OffsetTime, Instant, ZoneId) via PostgresJavaTimeMetaInstances. It introduces comprehensive array support for primitive and boxed types (Boolean, Integer, Long, Float, Double, String, UUID, BigDecimal) including both nullable and non-nullable variants, as well as a new arrayOfEnum helper for stricter enum array handling. PostgreSQL range types (int4range, int8range, numrange, daterange, tsrange, tstzrange) are now supported with RangeInstances. PostGIS geometry and geography types are mapped via PgisInstances and PgisGeographyInstances. A new Text typeclass is introduced to facilitate CSV/COPY operations with proper escaping. Finally, a comprehensive set of SQLSTATE constants is added to sqlstate.scala for better error handling.

modules/postgres/src/main/scala/doobie/postgres · high confidence

This change adds a new \hi\ (high-level) package under \org.typelevel.doobie.postgres\ that provides convenient wrappers for PostgreSQL-specific features. It exposes operations for managing large objects (including streaming copy from/to files and streams), accessing the \PGConnection\ directly (for backend PID, notifications, and prepare thresholds), and integrating with the CopyManager. These utilities lift lower-level free-monad operations into user-friendly \ConnectionIO\ and \PGConnectionIO\ effects, simplifying access to advanced Postgres capabilities.

modules/postgres/src/main/scala/doobie/postgres/hi · high confidence

The core module now includes a dedicated Scala 3 implementation for automatic \Read\ and \Write\ derivation using \scala.deriving.Mirror\, alongside Scala 2 support via Shapeless. This change introduces platform-specific files (\ReadPlatform.scala\, \WritePlatform.scala\, \GetPlatform.scala\, \PutPlatform.scala\) for both Scala 2 and Scala 3, enabling users to derive typeclass instances for case classes and enums without manual boilerplate. It also adds compatibility shims (\FactoryCompat\, \MultiVersionTypeSupport\) and a Scala 3-specific \OrElse\ implementation to support the derivation logic across versions.

modules/core/src/main · high confidence

The \modules/scalatest\ module now provides ScalaTest integration for verifying doobie query and update definitions at compile-test time. Users can mix in \IOChecker\ to use the \check\ and \checkOutput\ methods, which execute static analysis on \Query\ and \Update\ values and fail the test if the SQL does not typecheck or produce expected output schemas. Additionally, \IOAnalysisMatchers\ adds a \typecheck\ matcher factory, allowing assertions like \sql"select 1".query\[Int\] must typecheck\ to validate SQL syntax and types within ScalaTest specifications.

modules/scalatest/src/main · high confidence

A new \weaver\ module has been added to the project, providing integration with the Weaver testing framework. This module introduces an \IOChecker\ trait that allows users to validate the structure and output analysis of doobie \Query\ and \Update\ values directly within their test suites, ensuring SQL queries are correctly formed and typed before execution.

modules/weaver/src/main · high confidence

The \modules/example\ area now includes a comprehensive suite of new example applications demonstrating Doobie capabilities, including a simple ORM (\Orm.scala\), callable statements (\CallableStatementExample.scala\), free monad coproducts (\Coproduct.scala\), dynamic queries (\Dynamic.scala\), streaming data transfers (\GenericStream.scala\, \StreamingCopy.scala\), PostgreSQL-specific features like COPY IN (\PostgresCopyInCsv.scala\), Large Objects (\PostgresLargeObject.scala\), NOTIFY/LISTEN (\PostgresNotify.scala\), and Range types (\PostgresRange.scala\), alongside updated examples for Hikari connection pooling (\HikariExample.scala\) and custom type mappings (\CustomReadWrite.scala\, \OtherSchema.scala\). Additionally, new test fixtures (\AnalysisTest.scala\, \AnalysisTestScalaTest.scala\) have been added to support static analysis testing.

modules/example · high confidence

The \modules/free\ module now includes a dedicated logging and tracing subsystem. Users can observe SQL execution details via the new \LogHandler\ abstraction, which supports effectful logging (e.g., via JDK logging) and includes a \noop\ handler for disabling logs. The system captures structured \LogEvent\s (success, processing failure, execution failure) with SQL, parameters, labels, and timing metrics. Additionally, a \TraceEvent\ type and \Pos\ (source position) utility are introduced to support tracing and debugging by associating logs with source locations.

modules/free/src/main/scala/doobie/util · high confidence

This change introduces the \otel4s\ module, enabling OpenTelemetry tracing for Doobie database operations. It provides a \TracedInterpreter\ and \TracedTransactor\ that wrap execution in spans, configurable via \TracingConfig\ for span naming, query text/parameter capture, and attribute extraction. The module includes a \QueryAnalyzer\ trait for extracting semantic metadata (operation, table, summary) from SQL, \AttributesExtractor\ for decoding labels into attributes, and syntax helpers (\queryWithSummary\, \queryWithAttributes\) to attach tracing context to fragments.

modules/otel4s/src/main · high confidence

This change introduces new syntax extensions for the Postgres module, specifically adding \FragmentOps\ to support the PostgreSQL \COPY\ command. Users can now use \copyIn\ to efficiently insert data from a \Foldable\ collection or a streaming source (\Stream\[ConnectionIO, A\]\) into a table, with the streaming version handling chunking and resource management automatically. Additionally, a comprehensive set of \PostgresMonadErrorOps\ methods is added to \syntax.scala\, allowing users to handle specific PostgreSQL SQL state codes (such as warnings, connection exceptions, or data exceptions) via convenient extension methods like \onWarning\ or \onConnectionFailure\.

modules/postgres/src/main/scala/doobie/postgres/syntax · high confidence

The \World\ trait, along with its \IndexedWorld\ base, \ResultSetWorld\, and \StatementWorld\ implementations, has been removed from the \doobie.world\ package. This eliminates the previous state-transition-based API for managing database interactions, meaning users can no longer utilize these specific types for constructing or running database actions.

src/main/scala/doobie/world · high confidence

The \doobie\ package has removed several foundational source files that defined the library's previous database interaction model. Specifically, \InOut.scala\ (handling combined input/output parameters), \Param.scala\ (parameter setting logic), \Primitive.scala\ (basic JDBC type mappings), \SqlTypes.scala\ (JDBC type definitions), \Statement.scala\ (statement structure), and \Test.scala\ (sample code) have been deleted. This cleanup eliminates the old \Param\ and \InOut\ abstractions, simplifying the codebase by removing these specific implementation details.

src/main/scala/doobie · high confidence

The standard primitive type binding modules for Boolean, Int, String, and the Default configuration have been removed from the library. This eliminates the previous a-la-carte mapping implementations (such as mapping booleans to 'yes'/'no' strings or integers, and specific JDBC type aliases like \bigint\ or \varchar\) that were previously available in the \doobie.std\ package. Users relying on these specific legacy binding definitions will need to update their code to use the current standard mappings or define their own.

src/main/scala/doobie/std · high confidence

The Hikari module now provides a dedicated \Config\ case class that mirrors \com.zaxxer.hikari.HikariConfig\ properties, enabling structured configuration (e.g., via PureConfig) and simplifying setup. \HikariTransactor\ construction has been refactored to support this new config type with dedicated methods like \fromConfig\ and \fromConfigCustomEc\, which automatically manage the connection execution context and resource lifecycle, while also allowing separate effects for construction and execution via \WithResEffect\ variants.

modules/hikari/src/main · high confidence

Doobie now introduces a new \WeakAsync\ typeclass in the \modules/free\ module to unify algebras and interpreters. This change standardizes how asynchronous operations and cancellation are handled by providing a common interface (\fromFutureCancelable\) and specific utilities like \liftK\ and \liftIO\ for lifting effects, ensuring consistent behavior across different effect types.

modules/free/src/main/scala/doobie · high confidence

The Postgres module's free monad algebras (CopyIn, CopyManager, CopyOut, LargeObject, LargeObjectManager, PGConnection) and their Kleisli interpreters have been regenerated using FreeGen2. This update aligns the effect types with the WeakAsync typeclass, introducing support for cancellation, polling, and uncancelable regions across all Postgres-specific operations, while also updating the package namespace to org.typelevel.doobie.

modules/postgres/src/main/scala/doobie/postgres/free · high confidence

The repository has been restructured with new configuration files to standardize development and release processes. A \.scalafmt.conf\ file is introduced to enforce code formatting (version 3.11.5), and a \.git-blame-ignore-revs\ file is added to ignore automated formatting commits in git history. Automated pull request handling is configured via a new \.mergify.yml\ file, which auto-merges dependency updates and labels PRs by module. The \docker-compose.yml\ is updated to use official Postgres and MySQL images for local testing. Documentation is migrated to a microsite, with the \README.md\ updated to include community links and badges, and the \CHANGELOG.md\ deprecated in favor of GitHub Releases. Additionally, a \.jvmopts\ file is added to configure the JVM stack size, and the \LICENSE\ file is updated.

(repo-wide) · high confidence

The free algebras and Kleisli interpreters in the \modules/free\ module have been regenerated using FreeGen2 to align with Cats Effect 3. This update introduces support for cancellation and asynchronous operations via the \WeakAsync\ typeclass, adding smart constructors and algebraic operations for \uncancelable\, \poll\, \fromFutureCancelable\, and \onCancel\ across all JDBC effect types (such as \ConnectionIO\ and \PreparedStatementIO\).

modules/free/src/main/scala/doobie/free · high confidence

Add JMH benchmarks for read performance and COPY streaming; Added Java enum test fixture for PostgreSQL enum support; Added MUnit-based integration tests for Doobie query checking; Added Scala 3 test for Text derivation; Added Scala 3-specific test suites for enum and generic derivation; Added Specs2 integration tests for query analysis and matchers; Added comprehensive test suite for doobie.util components; Added comprehensive test suites for PostgreSQL module; Added empty platform-specific test suite for Scala 2; Added integration tests for Doobie's query checker using the Weaver test framework; Added platform-specific test suites for Doobie utilities; Added platform-specific test utilities for Scala binary version detection; Added property-based tests for H2 type mappings and query analysis; Added regression tests for specific GitHub issues; Added test arbitraries for Java time types; Added test arbitraries for SQL types and string generation; Added test coverage for doobie syntax components; Added test fixtures for PostgreSQL enum support; Added test for HikariTransactor connection lifecycle; Added test for WeakAsync liftK cancelation propagation; Added test suite for Doobie Refined integration; Added test utilities and sample classes for doobie testing; Added tests for H2 JSON support via circe; Added tests for Hikari connection cancellation and resource cleanup; Added tests for Hikari connection pool concurrency and stream prefetching; Added tests for HikariConfig default value parity; Added tests for Meta typeclass and tiemap validation; Added tests for PostgreSQL JSON/JSONB mapping with circe; Added tests for ScalaTest matchers and checker integration; Added tests for otel4s module components.

The project has been significantly upgraded to support Scala 2.12, 2.13, and 3.3.8, with core libraries updated to Cats Effect 3.7.1, FS2 3.14.0, Circe 0.14.16, and HikariCP 7.1.0. Database drivers have been bumped to PostgreSQL 42.7.12, PostGIS 2025.1.1, MySQL 26.7.0, and H2 2.4.240. The build system now uses sbt-typelevel for CI/release workflows, integrates MUnit 1.3.6 and Weaver 0.13.0 for testing, and enforces code generation checks via \freeGen2\ and header validation in GitHub Actions.

(dependencies) · high confidence

The project build has been upgraded to sbt version 1.13.0, with a comprehensive update of sbt plugins including sbt-paradox, sbt-site, sbt-ghpages, sbt-typelevel-ci-release, sbt-scoverage, sbt-updates, sbt-jmh, sbt-header, sbt-tpolecat, sbt-mdoc, sbt-scalafmt, sbt-projectmatrix, and sbt-scalafix. Additionally, a new FreeGen2 code generator plugin has been introduced to automate the generation of free algebras and interpreters, featuring configurable settings for class selection, package naming, import exclusions, and special handling for SQL types.

project · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 36 → 66 (+29.2)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 99 (-1.1)
• Architecture 69 → 93 (+24.0)
• Maturity 61 → 51 (-10.1)
• Readiness 19 → 73 (+54.3)
• Security 35 → 77 (+41.7)

• Coverage not measured — test suite did not build
• Dimension evaluation failed
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• No artifact signing
• No exposed public API
• …and 8 more

• Duplicated block (10 lines × 2) (modules/h2-circe/src/main/scala/doobie/h2/circe/Instances.scala)
• Duplicated block (6 lines × 2) (modules/h2/src/main/scala/doobie/h2/Metas.scala)
• Duplicated block (9 lines × 2) (modules/free/src/main/scala/doobie/free/kleisliinterpreter.scala)
• FileTooLong: free/kleisliinterpreter.scala (modules/free/src/main/scala/doobie/free/kleisliinterpreter.scala)
• Further sole-owners (lower concentration)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 13 more

• 21 commits — 21 feature/other, 0 fixes

• (repo) — 11 commits
• (root) — 6 commits
• project/plugins.sbt — 3 commits
• project/build.properties — 1 commit

• change: Merge pull request #2485 from typelevel/update/mysql-connector-j-26.7.0
• change: Merge pull request #2490 from typelevel/update/munit-1.3.5
• change: Merge pull request #2491 from typelevel/update/otel4s-core-trace-1.1.0
• change: Merge pull request #2494 from typelevel/update/sbt-1.13.0
• change: Merge pull request #2496 from typelevel/update/cats-effect-3.7.1
• change: Merge pull request #2498 from typelevel/update/mdoc-2.9.2
• change: Merge pull request #2499 from typelevel/update/munit-1.3.6
• change: Merge pull request #2502 from typelevel/update/fs2-core-3.14.0
• change: Merge pull request #2503 from typelevel/update/sbt-scalafix-0.14.8
• change: Merge pull request #2504 from typelevel/update/sbt-scalafix-0.14.9
• change: Merge pull request #2506 from typelevel/update/munit-cats-effect-2.2.1
• change: Update cats-effect, cats-effect-testkit to 3.7.1
• change: Update fs2-core, fs2-io to 3.14.0
• change: Update mdoc, sbt-mdoc to 2.9.2
• change: Update munit to 1.3.5
• change: Update munit to 1.3.6
• change: Update munit-cats-effect to 2.2.1
• change: Update otel4s-core-trace, ... to 1.1.0
• change: Update sbt, sbt-dependency-tree, ... to 1.13.0
• change: Update sbt-scalafix to 0.14.8
• …and 1 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

typelevel/doobie was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.