icha024 / spray-cloudant   0.1.3

Apache License 2.0 GitHub

Scala Cloudant client for Spray/Akka

Scala versions: 2.11

Scala Cloudant client for Spray/Akka

Build Status


Why another library? Most of the Cloudant/CouchDB libraries I've came across are overly complicated, and require a bit of a learning curve to use. Error handling and debugging response unmarshalling error wasn't very pleasant. They do have some really nice and advanced features, but I didn't really require them. Since I'm using Spray, and Cloudant already provide a HTTP API, it was fairly straight forward to create a new client library.

About 200 lines of Scala later, here is it.


  • CRUD for Database/Document/Bulk/Index/Views and Search Index/View method are provided.
  • Everything returns a Future[String] by default, this is the raw JSON response from Cloudant.
  • Unmarshalling is optional, with a .unmarshalTo[T] convenience method provided.
  • Exceptions (CloudantException) will come through the usual Future.failed channel.

Usage Example

Just extend the CloudantOps trait and the cloudant operations will be available.

class FoodService extends Actor with CloudantOps {
      // Alternatively: CloudantCredential(username, accountname, password)
      implicit val cloudantCred = new CloudantCredential(username, password)
      implicit val dbName  = "myDB"
      // Create doc via JSON directly
      // Notice _id and _rev field is omitted, this will create a new document.
      val doc = """{"food": "Pizza"}"""
      val response1: Future[String] = createOrUpdateDoc(doc)
      // Create doc via object
      case class MyFood(food: String)
      val myFood = MyFood("Pizza")
      val response2: Future[String] = createOrUpdateDoc[MyFood](myFood)
      // Create doc via object, then unmarshall the response
      val response3: Future[MyResponseType] = createOrUpdateDoc[MyFood](myFood).unmarshalTo[MyResponseType]

The best documentation is the code itself, it'll only take 2 minutes to glance through the code.

Client API Available

DB CRUD Operations
  • createDb
  • retrieveDb
  • retrieveAllDbs
  • deleteDb
Doc CRUD Operations
  • createOrUpdateDoc
  • createOrUpdateOrDeleteBulkDoc
  • retrieveDoc
  • deleteDoc
Index/View Operations
  • createOrUpdateIndex
  • createOrUpdateView
  • searchIndex
  • searchView

Unsupported Operations

  • Retrieve all doc on a DB
  • Retrieve DB changes
  • Querying view by composite key

Installing the client

Check Maven Central for the latest published version.

Maven Central




libraryDependencies += "com.clianz" % "spray-cloudant_2.11" % "0.1.3"

Transitive Dependencies

This library uses Scala 2.11, Spray/Akka, and the Shapeless library (via Spray-json-shapless).

+- org.scala-lang:scala-compiler:jar:2.11.7:compile
|  +- org.scala-lang:scala-library:jar:2.11.7:compile
|  +- org.scala-lang:scala-reflect:jar:2.11.7:compile
|  +- org.scala-lang.modules:scala-xml_2.11:jar:1.0.4:compile
|  \- org.scala-lang.modules:scala-parser-combinators_2.11:jar:1.0.4:compile
+- com.typesafe.akka:akka-actor_2.11:jar:2.4.4:compile
|  +- com.typesafe:config:jar:1.3.0:compile
|  \- org.scala-lang.modules:scala-java8-compat_2.11:jar:0.7.0:compile
+- io.spray:spray-client_2.11:jar:1.3.2:compile
|  +- io.spray:spray-can_2.11:jar:1.3.2:compile
|  |  \- io.spray:spray-io_2.11:jar:1.3.2:compile
|  +- io.spray:spray-http_2.11:jar:1.3.2:compile
|  |  \- org.parboiled:parboiled-scala_2.11:jar:1.1.6:compile
|  |     \- org.parboiled:parboiled-core:jar:1.1.6:compile
|  +- io.spray:spray-httpx_2.11:jar:1.3.2:compile
|  |  \- org.jvnet.mimepull:mimepull:jar:1.9.4:compile
|  \- io.spray:spray-util_2.11:jar:1.3.2:compile
\- com.github.fommil:spray-json-shapeless_2.11:jar:1.2.0:compile
   +- io.spray:spray-json_2.11:jar:1.3.2:compile
   +- org.slf4j:slf4j-api:jar:1.7.16:compile
   \- com.chuusai:shapeless_2.11:jar:2.3.0:compile
      \- org.typelevel:macro-compat_2.11:jar:1.1.1:compile

Spray-routing version

As mentioned in the official Spray documentation, if you are using Spray-routing, then you need the version built for shapeless.

This library was tested with: