Cloudant Data Layer as a Service

This add-on is operated by Cloudant

Scalable JSON DBaaS with built-in Search, Mobile Sync, Geo, & CouchDB API

Cloudant Data Layer as a Service

Last Updated: 10 April 2014

couchdb database nosql

Table of Contents

Cloudant is a NoSQL database-as-a-service (DBaaS) add-on.

  • Develop Epic Apps Fast - Get, Put, Index, and Query JSON data & attachments via a RESTful, CouchDB-compatible API.

  • Global Data Distribution – Cloudant distributes your data across a global network of data centers (AWS & others) to ensure low-latency, non-stop access from anywhere.

  • Advanced Data Management – enrich your apps with Lucene-powered full-text indexing & search, Data replication & sync to mobile devices, Incremental MapReduce for real-time analytics, Geo-spatial search

  • Managed for you – Experts at Cloudant monitor, operate and grow the data layer for you so you can stay focused on new development

Cloudant is accessible via a CouchDB-compatible RESTful JSON API and has supported client libraries for Java, Ruby, Python, Node.js, PHP, C#/.NET, and other CouchDB-compatible libraries.

Provisioning the add-on

Cloudant can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add cloudant:oxygen
-----> Adding cloudant:oxygen to my-app... done, v18 (free)

Once Cloudant has been added, a CLOUDANT_URL setting will be available in the app configuration and will contain the canonical URL used to access the newly provisioned Cloudant service instance. This can be confirmed using the heroku config:get command.

$ heroku config:get CLOUDANT_URL

Local setup

Cloudant is a hosted, managed database as a service, so there’s no database server software to install or configure. Since CouchDB and Cloudant have the same REST API you can use them the same way. You just need an HTTP client to interface with the database, and a JSON parser.

You can find a list of Cloudant-recommended client libraries here. You can also find a complete list of CouchDB-related libraries, frameworks and tools on the Apache CouchDB wiki

Using with Rails 3.x

The following code will GET the specified document from the “music” database and then print it to the page:

DB = "#{ENV['CLOUDANT_URL']}/music"
get "/doc/:doc" do
doc = RestClient.get("#{DB}/#{params[:doc]}")
@result = JSON.parse(doc)
haml :doc_id

The view would look something like:

%h1 A Doc from CouchDB!
- @result.each do |k,v|

You would request this page by pointing your browser to:

Monitoring & Logging

You can monitor Cloudant database activity via the Cloudant Dashboard (see below).

Cloudant activity can be observed within the Heroku log-stream.

$ heroku logs -t | grep 'cloudant pattern'

The Cloudant Dashboard

There is a rich set of Cloudant database administration, monitoring and development tools available to you at

The Cloudant dashboard provides a nice interface for adding & deleting databases, changing database access permissions, browsing, searching & editing JSON docs in your databases (via a Futon interface). It also displays real-time graphics showing database activity and performance.

To access your Cloudant dashboard, visit the Cloudant sign-in page and use the credentials found in your Heroku account CLOUDANT_URL parameter.

Migrating between plans

Cloudant offers several price plans, which vary based on the amount of data you store and how heavily you need to access it.

Changing your plan is straightforward and does not affect the databases you’ve created in Cloudant.

Use the heroku addons:upgrade command to migrate to a new plan.

For example, to migrate from the Cloudant Oxygen plan to the Cloudant Argon plan, do the following:

$ heroku addons:upgrade cloudant:argon
-----> Upgrading cloudant:argon to my-app... done, v18 ($15/mo)
       Your plan has been updated to: cloudant:argon

Removing the add-on

Cloudant can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove cloudant
-----> Removing cloudant from my-app... done, v4 (free)

Before removing Cloudant, you can export data in your databases by performing a CouchDB LIST command.


All Cloudant support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at the Cloudant Support Site.