principled database access for scala
Scala Shell
Latest commit 39823b2 Jan 19, 2017 @tpolecat committed on GitHub Merge pull request #439 from tpolecat/0.4.1-staging
0.4.1 staging
Permalink
Failed to load latest commit information.
project remove osgi Jan 3, 2017
yax Cats 0.9.0 Jan 18, 2017
.gitignore Ignore .idea Jan 12, 2017
.travis.yml scala 2.12.1 Dec 5, 2016
CHANGELOG.md readme-changelog Jan 20, 2017
LICENSE Update LICENSE Jan 26, 2015
PUBLISHING.md doc Jan 16, 2017
README.md readme-changelog Jan 20, 2017
build.sbt Cats 0.9.0 Jan 18, 2017
doobie_logo.svg update readme Sep 24, 2016
sbt Update to Scala 2.12.0 Nov 13, 2016
scalastyle-config.xml scalastyle May 3, 2016
version.sbt Setting version to 0.4.2-SNAPSHOT Jan 20, 2017
world.sql text ~> varchar Jan 17, 2015

README.md

doobie

Travis CI Join the chat at https://gitter.im/tpolecat/doobie Maven Central

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 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))

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.

Quick Start

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.

doobie status jdk scala scalaz scalaz-stream cats fs2 shapeless
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
0.2.4 eol 1.7+ 2.10, 2.11 7.1 0.8 -- -- 2.2
0.2.3 eol 1.6+ 2.10, 2.11 7.1 0.7 -- -- 2.2

To use doobie you need to add one of the following to your build.sbt.

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.

scalaz cats description
doobie-h2 doobie-h2-cats H2-specific type mappings.
doobie-hikari doobie-hikari-cats HikariCP connection pooling.
doobie-postgres doobie-postgres-cats PostgreSQL-specific type mappings.
doobie-specs2 doobie-specs2-cats specs2 support for typechecking queries.
doobie-scalatest doobie-scalatest-cats ScalaTest support for typechecking queries.

See the book of doobie for scalaz or cats 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.

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 #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 that includes doobie, let me know and I'll add it to this list.

Testing

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.