doobie is a pure functional JDBC layer for Scala and Cats. It is not an ORM, nor is it a relational algebra; it simply provides a functional way to construct programs (and higher-level libraries) that use JDBC. For common use cases doobie provides a minimal but expressive high-level API:
import doobie._ import doobie.implicits._ import cats.effect.IO import scala.concurrent.ExecutionContext import cats.effect.unsafe.implicits.global val xa = Transactor.fromDriverManager[IO]( "org.postgresql.Driver", "jdbc:postgresql:world", "postgres", "" ) case class Country(code: String, name: String, population: Long) def find(n: String): ConnectionIO[Option[Country]] = sql"select code, name, population from country where name = $n".query[Country].option
And then …
find("France").transact(xa).unsafeRunSync() // res0: Option[Country] = Some( // value = Country(code = "FRA", name = "France", population = 59225700L) // )
doobie is a Typelevel project. This means we embrace pure, typeful, functional programming, and provide a safe and friendly environment for teaching, learning, and contributing as described in the Scala Code of Conduct.
The current version is 1.0.0-RC1 for Scala 2.12/13/1 with
To use doobie you need to add the following to your
build.sbt. If you’re not using the Postgres or H2 add-ons you’ll also need to provide a JDBC driver for the database you’re using.
libraryDependencies ++= Seq( // Start with this one "org.tpolecat" %% "doobie-core" % "1.0.0-RC1", // And add any of these as needed "org.tpolecat" %% "doobie-h2" % "1.0.0-RC1", // H2 driver 1.4.200 + type mappings. "org.tpolecat" %% "doobie-hikari" % "1.0.0-RC1", // HikariCP transactor. "org.tpolecat" %% "doobie-postgres" % "1.0.0-RC1", // Postgres driver 42.3.1 + type mappings. "org.tpolecat" %% "doobie-specs2" % "1.0.0-RC1" % "test", // Specs2 support for typechecking statements. "org.tpolecat" %% "doobie-scalatest" % "1.0.0-RC1" % "test" // ScalaTest support for typechecking statements. )
See the documentation for more information on these add-ons.
Note that doobie is pre-1.0 software and is still undergoing active development. New versions are not binary compatible with prior versions, although in most cases user code will be source compatible. Starting with the 0.5.x we’re trying to be a bit more careful about versioning.
Documentation and Support
- Behold the sparkly documentation ← start here
- The Scaladoc will be handy once you get your feet wet.
- See the changelog for an overview of changes in this and previous versions.
- The Gitter Channel is a great place to chat!
- There is a Scala Exercises module, courtesy of our friends at 47 Degrees!
- There is also the source. Check out the examples too.
- If you have comments or run into trouble, please file an issue.
Presentations, Blog Posts, etc.
Listed newest first. If you have given a presentation or have written a blog post that includes doobie, let me know and I’ll add it to this list.
- Typechecking SQL queries with doobie by Bas Beelen, GoDataDriven, 13-Feb 2018
- Doobie - Feedback from the Trenches by François Armand, ScalaIO, October 2016
- Pure Functional Database Programming with Fixpoint Types by Rob Norris - Scala World, 2016 - slides
- The Functional Web Stack by Gary Coady - Dublin Scala Users Group, April 2016
- End to End and On The Level by Dave Gurnell - Typelevel Summit, Philadelphia, March 2016
- Programs as Values: JDBC Programming with doobie by Rob Norris - Scala by the Bay, 2015 - slides
- Typechecking SQL in Slick and doobie by Richard Dallaway
- DB to JSON with a Microservice by Da Terry - code
If you want to build and run the tests for yourself, you’ll need a local postgresql database. The easiest way to do this is to run
docker-compose up from the project root.
Building the Doc Site
I have to look this up every time. So here’s the dance.
% sbt sbt:doobie> project docs sbt:docs> clean sbt:docs> makeSite sbt:doce> ghpagesPushSite
Here’s a (non-exhaustive) list of companies that use doobie in production. Don’t see yours? You can add it in a PR!
- Banno at Jack Henry & Associates
- eBay Inc.
- RaiffeisenBank Russia
- The Guardian