[Couchdb Wiki] Update of "How to replicate a database" by BrianCandler

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The following page has been changed by BrianCandler:
http://wiki.apache.org/couchdb/How_to_replicate_a_database

------------------------------------------------------------------------------
  
  It is important to specific the database name in the URL as Futon does not assume anything with respect to the source or destination database based upon the originating or destination database.
  
- == Operational Hints =
+ == Operational Hints ==
+ 
+ Replication is one-way. In a multi-master scenario you have to issue one replication from A to B, and a separate one from B to A.
  
  Currently it seems that "pull" replication where you have a remote source and and a local target is much more reliable than "push" where you have it the other way around.
  
+ == Playing with Replication ==
+ 
+ It's straightforward to set up two test couchdb instances on the same machine. Here is local1.ini:
+ 
+ {{{
+ ; Remember to create the directories:
+ ;   mkdir -p /var/tmp/couchdb1/{data,log}
+ ;
+ ; Start using:
+ ;   couchdb -c /usr/local/etc/couchdb/default.ini -c local1.ini
+ 
+ [couchdb]
+ database_dir = /var/tmp/couchdb1/data
+ 
+ [log]
+ file = /var/tmp/couchdb1/log/couch.log
+ 
+ [httpd]
+ port = 5001
+ }}}
+ 
+ Similarly local2.ini:
+ 
+ {{{
+ ; Remember to create the directories:
+ ;   mkdir -p /var/tmp/couchdb2/{data,log}
+ ;
+ ; Start using:
+ ;   couchdb -c /usr/local/etc/couchdb/default.ini -c local2.ini
+ 
+ [couchdb]
+ database_dir = /var/tmp/couchdb2/data
+ 
+ [log]
+ file = /var/tmp/couchdb2/log/couch.log
+ 
+ [httpd]
+ port = 5002
+ }}}
+ 
+ Test they are both running:
+ 
+ {{{
+ $ curl http://localhost:5001/
+ {"couchdb":"Welcome","version":"0.9.0a738034-incubating"}
+ $ curl http://localhost:5002/
+ {"couchdb":"Welcome","version":"0.9.0a738034-incubating"}
+ }}}
+ 
+ === Create and replicate a document ===
+ 
+ {{{
+ $ curl -X PUT http://localhost:5001/sampledb
+ {"ok":true}
+ $ curl -X PUT http://localhost:5002/sampledb
+ {"ok":true}
+ 
+ $ curl -X PUT -d '{"hello":"world"}' http://localhost:5001/sampledb/doc1
+ {"ok":true,"id":"doc1","rev":"3851869530"}
+ 
+ $ curl -X POST -d '{"source":"http://127.0.0.1:5001/sampledb","target":"sampledb"}' \
+     http://localhost:5002/_replicate
+ {
+   "ok":true,
+   "session_id":"7118d54c40761eba83454aabae8ea91b",
+   "source_last_seq":0,
+   "history":
+   [
+     {
+       "start_time":"Wed, 28 Jan 2009 16:26:09 GMT",
+       "end_time":"Wed, 28 Jan 2009 16:26:09 GMT",
+       "start_last_seq":0,
+       "end_last_seq":1,
+       "missing_checked":1,
+       "missing_found":1,
+       "docs_read":1,
+       "docs_written":1
+     }
+   ]
+ }
+ }}}
+ 
+ ''POST response has been reformatted for clarity''
+ 
+ {{{
+ $ curl http://127.0.0.1:5001/sampledb/doc1
+ {"_id":"doc1","_rev":"3851869530","hello":"world"} 
+ $ curl http://127.0.0.1:5002/sampledb/doc1
+ {"_id":"doc1","_rev":"3851869530","hello":"world"} 
+ }}}
+ 
+ === Create conflicting updates ===
+ 
+ ''Note: the updates have to be made on separate databases. Update conflicts can't occur within a single database; because you provide the original _rev, if someone else has already changed the document, the second update is rejected.''
+ 
+ {{{
+ $ curl -X PUT -d '{"_rev":"3851869530","hello":"fred"}' http://localhost:5001/sampledb/doc1
+ {"ok":true,"id":"doc1","rev":"132006080"}
+ $ curl -X PUT -d '{"_rev":"3851869530","hello":"jim"}' http://localhost:5002/sampledb/doc1
+ {"ok":true,"id":"doc1","rev":"2575525432"}
+ 
+ $ curl -X POST -d '{"source":"http://127.0.0.1:5001/sampledb","target":"sampledb"}' \
+     http://localhost:5002/_replicate
+ {"ok":true,"session_id":"fe1ec1c66b0b916e7e87dd635b4dc572","source_last_seq":0,"history":
+ [{"start_time":"Wed, 28 Jan 2009 16:28:36 GMT","end_time":"Wed, 28 Jan 2009 16:28:36 GMT",
+ "start_last_seq":0,"end_last_seq":2,"missing_checked":1,"missing_found":1,"docs_read":1,"docs_written":1}]}
+ 
+ $ curl http://127.0.0.1:5001/sampledb/doc1
+ {"_id":"doc1","_rev":"132006080","hello":"fred"}
+ $ curl http://127.0.0.1:5002/sampledb/doc1
+ {"_id":"doc1","_rev":"2575525432","hello":"jim"}
+ }}}
+ 
+ At this point you can see the two databases still have different ideas about this document. You need to replicate back the other way as well:
+ 
+ {{{
+ $ curl -X POST -d '{"target":"http://127.0.0.1:5001/sampledb","source":"sampledb"}' \
+     http://localhost:5002/_replicate
+ 
+ {"ok":true,"session_id":"da0a07a0f9c9fb5c2d2e2769229257df","source_last_seq":0,"history":
+ [{"start_time":"Wed, 28 Jan 2009 16:30:23 GMT","end_time":"Wed, 28 Jan 2009 16:30:23 GMT",
+ "start_last_seq":0,"end_last_seq":3,"missing_checked":2,"missing_found":1,"docs_read":1,"docs_written":1}]}
+ 
+ $ curl http://127.0.0.1:5001/sampledb/doc1?revs=true
+ {"_id":"doc1","_rev":"2575525432","hello":"jim","_revs":["2575525432","3851869530"]}
+ 3$ curl http://127.0.0.1:5002/sampledb/doc1?revs=true
+ {"_id":"doc1","_rev":"2575525432","hello":"jim","_revs":["2575525432","3851869530"]}
+ }}}
+ 
+ The two machines now agree on one document and revision history, but the conflict (and conflicting version) is not shown. You have to ask for this explicitly with ''conflicts=true''
+ 
+ {{{
+ $ curl http://127.0.0.1:5001/sampledb/doc1?conflicts=true
+ {"_id":"doc1","_rev":"2575525432","hello":"jim","_conflicts":["132006080"]}
+ $ curl http://127.0.0.1:5002/sampledb/doc1?conflicts=true
+ {"_id":"doc1","_rev":"2575525432","hello":"jim","_conflicts":["132006080"]}
+ }}}
+