IBM Developer Advocacy

Cloudant Learning Center – Get Started

Watch this short video to see how to provision IBM Cloudant on Bluemix, create a database, load some data, and see a quick tour of the Cloudant dashboard.

Create a Cloudant account

You can create a Cloudant account and connect your Bluemix app to a Cloudant database in one of the following ways:

After you connect, understand how the connection works and where to find details.

Add Cloudant Service through the Bluemix dashboard

If you’re working in Bluemix, add a new Cloudant data service in just a few clicks:

  1. Visit your Bluemix dashboard .
  2. Click Catalog.
  3. Check the Data & Analytics category.
  4. Select Cloudant NoSQL DB.
  5. Enter a descriptive name in the Service name field.
  6. In the Connect to drop-down list, select the app you want to access Cloudant.
  7. Click Create.
  8. From your dashboard, open the Cloudant service instance.
  9. Locate your database details under the Service Credentials tab. If the credentials were not auto-generated, click New credentials to add credentials.
  10. Back on the Manage tab, click Launch to open the Cloudant dashboard.

Deploy and connect manually

If you prefer to work locally, you can deploy an app to Bluemix and add Cloudant service from a command line interface by using the CloudFoundry cf tool.

  1. Install the Cloud Foundry command line interface and connect to Bluemix .
  2. Create a Cloudant service within Bluemix:
    $ cf create-service cloudantNoSQLDB Shared <cloudant_service_name> 
  3. Bind the service to your app:
    $ cf bind-service <bluemix-app-name> <cloudant-service-name>

Connect an existing Cloudant database to your Bluemix app

So you created a Cloudant database on and now you’ve got a nifty Bluemix app. How do you connect them together?

The answer is: Don’t add Cloudant Service via Bluemix. Instead, within your app’s code, call your existing Cloudant database through the HTTP API as you normally would. More on using the API.

Why bypass Bluemix’s Cloudant Service? When you add the Cloudant Service to your Bluemix app, Bluemix creates a new mulit-tenant instance of Cloudant, and you can’t edit the connection to point to your existing database. So don’t add the Cloudant service, but go ahead and take advantage of other Bluemix services and features.

Can I replicate instead?

If your database is on a dedicated cluster, you must connect only through your app’s code. But, if you’re using a multi-tenant instance of Cloudant, and you don’t mind moving your data, you could create a new Cloudant service on Bluemix and replicate your existing data into that new Bluemix database service. To do so:

  1. In Bluemix, add Cloudant Service.
  2. Get database details from the service credentials (read how in the next section).
  3. Set up a replication job to copy data from your existing database to the new Bluemix Cloudant service database.

How the connection works

Once you connect your Bluemix app to Cloudant, you’ll find the following connection details service credentials.

  "cloudantNoSQLDB": {
    "name": "appname-cloudant-service",  
    "label": "cloudantNoSQLDB",   
    "plan": "shared",
    "credentials": {
      "username": "randomlyassignedusername",  //Bluemix-generated random string 
      "password": "secret",   //Bluemix-generated random string
      "host": "", //yourhost is a Bluemix-generated random string
      "port": 443,
      "url": "" //url of your app's Cloudant instance

Access service credentails in one of two ways:

Access Cloudant through the dashboard

Once you’ve added Cloudant service, you can access your app’s Cloudant dashboard through Bluemix:

  1. In Bluemix, open the app using the Cloudant service.
  2. Navigate to the Connections tab.
  3. Click the Cloudant service.
  4. On the Cloudant service launch page, click Launch.

    Your app’s instance of Cloudant opens to the dashboard screen.