SAP: Streamline Processes and Gain Business Insights in the Cloud

Learn how to drive profitable growth affordably and without complexity for your small business using SAP Business One Cloud.

GET YOUR FREE COPY TODAY!!

Monday, 13 April 2015

Getting started with CouchDB-Part 3

Getting started with CouchDB-Part 3
Basic Replication and Clustering

In the previous POST, we saw few simple commands using which you can create, list, populate and delete documents and databases. In this post, I'll be walking you through simple steps using which you can replicate and cluster CouchDB Databases.


Replication
The replication is an incremental one way process involving two databases (a source and a destination).

The aim of the replication is that at the end of the process, all active documents on the source database are also in the destination database and all documents that were deleted in the source databases are also deleted (if exists) on the destination database.

NOTE: The replication process only copies the last revision of a document, so all previous revisions that were only on the source database are not copied to the destination database.

Replication in CouchDB is peer-based and involves a source and a destination database, which can be one the same or on different CouchDB instances.  

A replication job is triggered by storing a special replication document in the replicator (_replicate) database. Its status can be inspected through the "_active_tasks" API. A replication can be stopped by deleting the document, or by updating it with its cancel property set to true.
Let us look at how to perform replication on the same CouchDB Instance:

First, create two separate databases on the same CouchDB instance. In this case, we have created "db-01" and "db-02"

# curl -X PUT http://127.0.0.1:5984/db-01

# curl -X PUT http://127.0.0.1:5984/db-02




Next, create an empty document on either of the database. Note that the database where the document is created will now become the source from where the contents will be replicated over to the target database.

# curl -X POST  http://127.0.0.1:5984/db-01 \
   -H "Content-Type: application/json" \
   -d '{}'

You can populate the document later once the replication has started.




Next, setup the replication process itself. Here, "db-01" is the source and "db-02" is the target database

# curl -X POST  http://127.0.0.1:5984/_replicate \
   -H "Content-Type: application/json" \
   -d \
   '{
      "source":"db-01",
      "target":"db-02",
   }'




To make sure the replication has indeed started, try fetching something from the target database. You should see the "doc_count" as 1 now, meaning there is one document in this database.

# curl -X GET http://127.0.0.1:5984/db-02




You can optionally set the replication to take place continuously as well by setting the "continuous" attribute to "true" as shown:

# curl -X POST  http://127.0.0.1:5984/_replicate \
   -H "Content-Type: application/json" \
   -d \
   '{
      "source":"db-01",
      "target":"db-02",
      "continuous":true
    }'

Note the "_local_id" attribute value provided.




You can list all current running tasks to check if the replication is working using the "_active_tasks" command as shown:

# curl -X GET  http://127.0.0.1:5984/_active_tasks

You should see an output similar to the one shown below:

[
   {"pid":"<0.16302.1297>",
   "checkpoint_interval":5000,
   "checkpointed_source_seq":1,
   "continuous":true,
   "doc_id":null,
   "doc_write_failures":0,
   "docs_read":0,
   "docs_written":0,
   "missing_revisions_found":0,
   "progress":100,"
   replication_id":"fb577a13ef44561e67e4a849ca81ec4e+continuous",
   "revisions_checked":1,
   "source":"db-01",
   "source_seq":1,
   "started_on":1427875738,
   "target":"db-02",
   "type":"replication",
   "updated_on":1427875833}
]



To cancel an active replication task, either delete the document, or update it with its "cancel" property set to "true". Remember to pass the "_local_id" of the replication task as shown:

# curl -X POST  http://127.0.0.1:5984/_replicate \
   -H "Content-Type: application/json" \
   -d \
   '{
      "_local_id":"96b5d289afa4d7c82622f7d28e7528a4+continuous",
      "cancel":true
   }'





CouchDB also allows you to replicate your database on more than one CouchDB instance. In this example, I have CouchDB running on two servers; DB-HOST-1 and DB-HOST-2. To begin with, create a database on each of the two servers:

# curl -X PUT http://192.168.0.40:5984/db-01




Follow the same process on the second CouchDB Instance:

# curl -X PUT http://192.168.0.45:5984/db-02




Next, as we did before, create an empty document on either of the database you select as the source:

# curl -X POST  http://192.168.0.40:5984/db-01 \
   -H "Content-Type: application/json" \
   -d '{}'

You can populate the document later once the replication has started.




Next, setup the replication process itself. Here, "db-01" is the source and "db-02" is the target database

# curl -X POST  http://127.0.0.40:5984/_replicate \
   -H "Content-Type: application/json" \
   -d \
   '{
      "source":"http://192.168.0.40:5984/db-01",
      "target":"http://192.168.0.45:5984/db-02",
      "continuous":true
   }'




To make sure the replication has indeed started, try fetching something from the target database. You should see the "doc_count" as 1 now, meaning there is one document in this database.

# curl -X GET http://192.168.0.45:5984/db-02





You can optionally use CouchDB's UI, Futon as well to setup a replication process.

Access a web browser and type in the following:

http://<COUCHDB_SERVER_IP>:5984/_utils

From the "Overview" page, select the "Replicator" option from the right-hand side options tab as shown. When you click the Replicator you will be presented with the "Replicator screen". This allows you to start replication between two databases by filling in or select the appropriate options within the form provided.



To start a replication process, either the select the "local database" or enter a "remote database" name into the corresponding areas of the form. To enable continuous replication, select the "Continuous" checkbox.

To start the replication process, click the "Replicate" button. The replication process should start and will continue in the background. If the replication process will take a long time, you can monitor the status of the replication using the "Status" option under the Tools menu.


That's all there is for this post.. stay tuned for lots more tutorials coming your way soon!

Cheers!