doobie is a pure functional JDBC layer for Scala. It is not an ORM, nor is it a relational algebra; it just provides a principled way to construct programs (and higher-level libraries) that use JDBC. doobie introduces very few new abstractions; if you are familiar with core typeclasses like
Monad you should have no trouble here.
For common use cases doobie provides a minimal but expressive high-level API:
import doobie.imports._, scalaz.effect.IO val xa = DriverManagerTransactor[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 scala> find("France").transact(xa).unsafePerformIO res0: Option[Country] = Some(Country(FRA,France,59225700))
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 Typelevel Code of Conduct.
Recent releases and dependencies are shown below. The current release is 0.4.1 … if you wish to use an older version please switch to the associated tag. The remainder of this document assumes you're using the current release.
|0.4.1||current||1.8+||2.10, 2.11, 2.12||7.2||0.8||0.9||0.9||2.3|
|0.4.0||current||1.8+||2.10, 2.11, 2.12||7.2||0.8||0.8||0.9||2.3|
|0.3.0||eol||1.8+||2.10, 2.11, 2.12||7.2||0.8||--||--||2.3|
To use doobie you need to add one of the following to your
libraryDependencies += "org.tpolecat" %% "doobie-core" % "0.4.1" // scalaz + scalaz-stream "org.tpolecat" %% "doobie-core-cats" % "0.4.1" // cats + fs2
If you are using Scala 2.10 you must also add the paradise compiler plugin.
addCompilerPlugin("org.scalamacros" % "paradise" % "2.1.0" cross CrossVersion.full)
It is likely that you will want one or more add-on libraries. doobie provides the following, which have the same version as
doobie-core[-cats] and are released together.
||H2-specific type mappings.|
||HikariCP connection pooling.|
||PostgreSQL-specific type mappings.|
||specs2 support for typechecking queries.|
||ScalaTest support for typechecking queries.|
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.
Documentation and Support
- See the changelog for an overview of changes in this and previous versions.
- Behold the book of doobie for scalaz and cats ← start here
- There is a Scala Exercises module, courtesy of our friends at 47 Degrees!
- The scaladoc will be handy once you get your feet wet.
- There is also the source. If you're here you know where to look. Check the examples.
- If you have comments or run into trouble, please file an issue.
- Find tpolecat on the FreeNode
#scalachannel, or join the Gitter Channel.
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.
- 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. Tests are run as the default postgres user, which should have no password for access in the local environment. You can see the
before_script section of the .travis.yml file for an up-to-date list of steps for preparing the test database.