Cloudant DBaaS 101

I have been playing with DBaaS and I am very impressed. If you want a NoSQL scalable database goto and create free account. They have reasonable rates once you go beyond the free tier but you will never get a bill if you use less than $50 a month (approx 1,600,000 light reads or 300,000 heavy writes) or 50GB. Cloudant can handle billions of transactions a day, replicate data across data centres, secure/encrypt your data etc

The hardest part is understanding how to prepare HTTP requests to the server (and formatting/reading the JSON payloads) but that is way simple than dealing with the hell of SQL and HTTP forms, sessions and SQL injection stuff. When you signup choose your name (e.g “testuser”) this will become the URL to your database (“”). You can also choose where your database is located (US, London, Singapore etc) but don’t worry, this can be changed later. By default all traffic to/from cloudant is via https (at no cost) unless you opt out.

If you are unsure just goto and wait 5 min and a popup live chat window will appear and ask away. You can also follow @cloudant on twitter, join the community on IRC or email

My blog post is certainly not going to teach your the right terminology (for that go here and but in a few minutes you can easily create a table, write new records, query and modify records in minutes.

How to create a table

Once you have created an account you can create tables (database) via the Cloudant url (https://{yourusername} or remotely via a number of ways (e.g a Python Script). You do not need to use Python, you could use .NET, HTTP code from an Arduino or PHP code on a website. As long as you can send a http request with authorisation (login details) and attach/decode JSON you can talk to/from a Cloudant DBaaS.

import requests
import json
auth = ('yourusername', 'yourpassword')
post_url = "".format(auth[0])
r = requests.put(post_url, auth=auth)
print json.dumps(r.json(), indent=1)

This will create table called “testtable”

If you do something wrong cloudant will let you know via the API and HTTP response code Always check the response codes.

How to save a new record into a table

Obviously you need to decide on the table names and fields in your database table but here is a quick way to throw a record at the database above with python.

import requests
import json
doc = {'username':'kerrie','high_score':550, 'level':3}
auth = ('yourusername', 'yourpassword')
headers = {'Content-type': 'application/json'}
post_url = "".format(auth[0])
r = requests.put(post_url, auth=auth, headers=headers, data=json.dumps(doc))
print json.dumps(r.json(), indent=1)

You can see that we are creating a JSON array (containing some key pair values and passing that to a URL via HTTP packet data).

How to query a record

Simply query the URL (

and process the JSON returned.

import requests
import json
auth = ('yourusername', 'yourpassword')
get_url = "".format(auth[0])
r = requests.get(get_url, auth=auth)
print json.dumps(r.json(), indent=1)

There is a whole topic on querying by ID’s and versioning that is not covered here.

How to query all record

You can also return all records in a table by querying the URL:

Results would be returned something like this:


There is also syntax for maximum items returned and pagination that you can read up on.

Now that you understand the basics you can plan how you want to talk to your database, it could be via .NET, PHP, Perl, Corona SDK or via Python. Do check out the official create/read/update and delete examples and read the getting started guide.

In the next post I will add some CoronaSDK to Cloudant tips.

Edit 2/Jan/2015: Cloudant have increased the freebies 10 fold (I have updated the prices above).