Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

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:



Scala Cloudant client for Spray/Akka







No packages published