freskog / doobie

principled database access for scala

doobie

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 basic scalaz typeclasses like Functor and 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))

Quick Start

The current release is 0.2.2, which works on Scala 2.10.5 and 2.11 with

• scalaz 7.1
• scalaz-stream 0.7a
• shapeless 2.2.0

You should expect minor breaking changes for at least the next few versions, although these will be documented and kept to a minimum. To use doobie you need to add the following to your build.sbt.

resolvers ++= Seq(
  "tpolecat" at "http://dl.bintray.com/tpolecat/maven",
  "Scalaz Bintray Repo" at "http://dl.bintray.com/scalaz/releases"
)

libraryDependencies += "org.tpolecat" %% "doobie-core" % "0.2.2"

If you are using Scala 2.10.5 you must also add the paradise compiler plugin.

addCompilerPlugin("org.scalamacros" % "paradise" % "2.0.1" 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 and are released together.

• doobie-contrib-h2 for H2-specific type mappings.
• doobie-contrib-hikari for HikariCP connection pooling.
• doobie-contrib-postgresql for PostgreSQL-specific type mappings.
• doobie-contrib-specs2 for specs2 support for typechecking queries.

See the book of doobie for more information on these add-ons.

Documentation and Support

• See the changelog for an overview of changes in this and previous versions.
• Behold the book of doobie ← start here
• 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 #scala channel, or join the Gitter Channel.

Presentations, Blog Posts, etc.

Listed newest first. If you have given a presentation or have written a blog post on doobie, let me know and I'll add it to this list.

• Typechecking SQL in Slick and doobie by Richard Dallaway
• Programs as Values: Pure Functional Database Access in Scala by Rob Norris
• DB to JSON with a Microservice by Da Terry (code here).