Developing software in the Real World

Kitura tutorial part 2: CouchDB

In part one we set up Swift and build a “hello world” Kitura application, so we are well placed to build an API that actually does something. This API will manage a list of books. Clearly, we’ll need to store our books somewhere and I’ve chosen CouchDB for this tutorial.

To access CouchDB, you use HTTP which makes it very easy to work with curl or any other HTTP client. The docs are useful!

This part of the tutorial concentrates solely on setting up CouchDB, populating it and ensuring that we can operate with it.

The data

For this project we’re going to manage a list of books. Each book will have the following fields:

  • Title
  • Author
  • ISBN

This isn’t a complicated database!

Install CouchDB

On OS X, you can install CouchDB using homebrew:

On Linux, install via apt:

You now have a local CouchDB installation on http://localhost:5984.

The next step is to set up an admin user:

Select any username and password that you like, but don’t forget it! I’m going to use rob/123456 throughout the rest of the tutorial. If the command succeeded, it returns an empty string.

Populate CouchDB with some data

To populate our database, we need some data, a design document and a bash script to do the work. We’ll create three files in a new directory called scripts:

  • scripts/books.json
  • scripts/main_design.json
  • scripts/seed_couchdb.sh

These are the files. Create them in scripts.

scripts/books.json

This JSON file contains a ‘docs’ array containing a set of objects for each book in our database. As CouchDB is a document database, we don’t have tables are we would do in a standard RDBMS, so I’ve also chosen to have an additional property called type which is set to book. We don’t techncially need this, but it makes it easier to write our views as we can test for the type to ensure we have a book document.

scripts/main_design.json

The main design document contains our list of views. In this case we have a single view called all_books which will emit all records of type “book”. In CouchDB, each view is a JavaScript function that outputs the documents that match a given criteria. For all_books, we simply check that the type is book and if it is, emit the document using the compound key of author and title so that the list is ordered by author, then book title.

scripts/seed_couchdb.sh

This is quite a long script as half of it concerned with parsing the command line to collect the username, password and url to our CouchDB instance. While we could hard-code these details, it’s convient to be able to re-use this script with other CouchDB instances hosted on the Internet.

We also need to make the seed_couchdb.sh file executable:

Seed the database

Now that we have our JSON data files and a bash script to use, we can populate our CouchDB database:

(use the username and password that you set up earlier!)

The script will output some JSON for each curl command run and finish with this line:

Test that the data exists

You can check the data has been populated into your database either by using Futon by opening http://localhost:5984/_utils in your browser. More easily, we can also use curl:

which will output something like:

(The jq tool nicely formats the JSON to make it readable)

The key information is that the doc_count is 28. This is our 27 books plus one design document.

Database access via curl

We can also retrieve the output of the design document’s view:

This will return all the books in the database.

Similarly we can add a new book by POSTing to the database:

which will output something like:

We can edit a book, by PUTing a complete representation to the record’s URL and including the current revision in the body as the _rev key:

The output is the same as for creating a record, except that the revision number is different:

To delete the a book, we use the DELETE HTTP verb:

We now have a working CouchDB instance with some data in it so we can move along to part 3 and retrieve it in our Swift application!

Aside: Update the docker-composer file

If you’re using docker compose, then update the docker-compose.yml file to start up a CouchDB container and also seed the database:

docker-compose.yml

Tutorial navigation

GitHub repository: kitura_bookshelfapi