Friday, 10 April 2015

Getting started with CouchDB-Part 2

Getting started with CouchDB-Part 2
Working with CouchDB- Basic Commands



In PART 1 of this series of tutorials, we learned some quick facts about CouchDB and also saw an easy way to install and configure it. In this post, I'll be walking you through some basic commands and also show you how to work with Futon; a web interface for managing CouchDB.

Part 1: Installation and Configuration
Part 2: Running basic commands
Part 3: Clustering
Part 4: Load balancing



Commands:
First off, let's check whether our CouchDB instance is up and running or not. For that, simply run a curl command as shown:

# curl -X GET http://192.168.0.40:5984

You should get a response similar to this:
{"couchdb":"Welcome","uuid":"e833c5cfb43d96001433cae620e74595","version":"1.6.1","vendor":{"name":"The Apache Software Foundation","version":"1.6.1"}}



Next, let's create a simple Database. 

# curl -X PUT http://192.168.0.40:5984/<DATABASE_NAME>

You should see a response as: {"ok":true}

This means you successfully created a new database on CouchDB.

A few important pointers to remember while creating a database:

  • Use Lowercase characters (a-z)
  • You can use Digits (0-9) while naming your database but the first character has to be an alphabet
  • You can use any of the characters _, $, (, ), +, -, and / while naming your database but the first character has to be an alphabet



If you try to add a database with the same name, then obviously CouchDB will not allow you to do that and prompt you that "the file already exists"



You can obtain additional details about your database by simply querying against it:

# curl -X GET http://192.168.0.40:5984/<DATABASE_NAME>

This will provide you the following output:

{
   "db_name":"stuff",
   "doc_count":0,
   "doc_del_count":0,
   "update_seq":0,
   "purge_seq":0,
   "compact_running":false,
   "disk_size":79,
   "data_size":0,
   "instance_start_time":"1427795965351454",
   "disk_format_version":6,
   "committed_update_seq":0
}


CouchDB also allows you to list all your databases in one go using some built in commands, such as "_all_dbs"

# curl -X GET http://192.168.0.40:5984/_all_dbs

The output shows you a list of all the databases present on this particular CouchDB Instance. Also worth noting here is the presence of two CouchDB internal databases called as "_users" and "_replicator". We will be talking about these two in the coming tutorials.

["_replicator","_users","oranges","stuff"]
NOTE: Additional to "_all_dbs", CouchDB also provides the following interfaces to query your Couch Instance:
  • /_active_tasks: Lists actively running tasks
  • /_db_updates: Lists all database events
  • /_log: Prints CouchDB's logs
  • /_replicate: Used during the replication process (more on this in next post)
  • /_restart: Restarts CouchDB Instance
  • /_stats: Prints statistics of the CouchDB server
  • /_utils: Accesses the built-in Futon administration interface for CouchDB
  • /_uuids: Used to request one or more UUIDs from CouchDB
  • /_config: Prints entire CouchDB configuration info
You can find the complete list HERE



Now that our database is ready, lets populate it with a "Document". Documents are the primary unit of data in CouchDB and consist of any number of fields and attachments. Documents also include metadata that’s maintained by the database system. Document fields are uniquely named and contain values of varying types (text, number, boolean, lists, etc), and there is no set limit to text size or element count.

To add a document to a database, we use the same curl command but with a "-d" paramenter to pass our data, for e.g:

#  curl -X POST http://192.168.0.40:5984/stuff \
   -H 'Content-type: application/json' \
   -d '{
   "fruit":"apple",
   "car":"fiat",
   "random stuff":"meeoooowwww"
 }'

You should see a similar response once you have added your document. The output contains two important fields: 
  • "id" --> Basically a unique ID that identifies your document.
  • "rev" --> Revision ID. Revisions are important in CouchDB. You cannot update a document in the database without knowing the current revision of the document. This is a failsafe to ensure that you do not just overwrite the document with a new version.


{"ok":true,"id":"0ca55157fc3fdd5528f7d98934002b2b","rev":"1-c31f8f2f547922f63fd3195547db7180"}


To list the document's contents, you simply use the GET command along with the "Document's ID" as shown:

# curl -X GET http://192.168.0.40:5984/<DATABASE_NAME>/<DOCUMENT_ID>



If you wish to update a particular entry from your document, you can do that as well by providing the document's "Revision ID" along with the field that you wish to update as shown:

# curl -X POST http://192.168.0.40:5984/stuff \
   -H 'Content-type: application/json' \
   -d '{
   "car":"BMW",
   "-rev":"1-c31f8f2f547922f63fd3195547db7180"
 }' 



Deleting a Database is simple as well, just pass the database name with the DELETE parameter as show:

# curl -X DELETE http://192.168.0.40:5984/stuff



The best part of CouchDB is that it comes with its own web-based UI as well called Futon. It provides a basic interface to the majority of the functionality, including the ability to create, update, delete and view documents and views, provides access to the configuration parameters, and an interface for initiating replication.

To access Futon, simply open up a browser and type in the following:

http://<COUCHDB_SERVER_IP>:5984/_utils

You will be presented with a similar "Home" screen or the "Overview" tab that basically shows you a list  of databases that you have created. To the right of the UI, there is a "Tools" section, where you can select different options such as "Configuration", "Replication" and even view the current "Status" of your CouchDB instance.

To create a new database, click the "Create Database" button. You will be prompted for the database name, as shown




Provide a suitable name for your database and click "Create" once done.



This will automatically take you to your newly created database. Here, you can create documents, manage the database's security and even delete the database if required.

For now, let us create a sample document for our database. Click "New Document"



The document gets an "_id" field by default. You can change its value to something a bit more meaningful if you wish. Click on "Add Field" to add a new row in your document. Once done, remember to save the changes by selecting the "Save Document" button.



Fulton will automatically change the "Revision ID/ _rev" in case you edit a field of the document. you can traverse between the different revisions of the document by using the tabs as shown below: 



Optionally you can also view the "Source" of your document by selecting the "Source" tab as shown. This will provide you the contents of your document in a JASON format.




In the next PART of this series, we will be looking at some simple ways to create a Cluster between two CouchDB instances so stay tuned for much more coming your way soon!


Cheers!



No comments :

Post a Comment