couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Couchdb Wiki] Update of "Replication" by JensAlfke
Date Sat, 19 May 2012 04:02:20 GMT
Dear Wiki user,

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

The "Replication" page has been changed by JensAlfke:
http://wiki.apache.org/couchdb/Replication?action=diff&rev1=40&rev2=41

  Changes on the master will not automatically replicate to the slaves. See “Continuous
Replication” below.
  
  === Run Replication ===
- Replication is triggered by sending a POST request to the `_replicate` URL with a JSON object
in the body that includes a `source` and a `target` member.
+ Replication is triggered by sending a POST request to the `_replicate` URL. The body is
JSON with the following allowed fields:
+ 
+ ||'''Field Name''' ||'''Description''' ||
+ ||''source'' || Identifies the database to copy revisions from. Can be a string containing
a local database name or a remote database URL, or an object whose `url` property contains
the database name or URL. ||
+ ||''target'' || Identifies the database to copy revisions to. Same format and interpretation
as `source`. ||
+ ||''cancel'' || Include this property with a value of `true` to cancel an existing replication
between the specified `source` and `target`. ||
+ ||''continuous'' || Include this property with a value of `true` to make the replication
''continuous''. Default value is `false`. ||
+ ||''doc_ids'' || Optional array of document IDs; if given, only these documents will be
replicated. ||
+ ||''filter'' || Name of a ''filter function'' that can choose which revisions get replicated.
||
+ ||''proxy'' || Optional proxy server URL. ||
+ ||''query_params'' || Optional object containing properties that are passed to the filter
function. ||
+ 
+ 
+ The `source` and a `target` fields indicate the databases that documents will be copied
''from'' and ''to'', respectively. Use just the name for a local database, or the full URL
for a remote database. A local-to-remote replication is called a ''push'', and remote-to-local
is called a ''pull''. Local-to-local or even remote-to-remote are also allowed, but rarer.
For example:
  
  {{{
  POST /_replicate HTTP/1.1
  
  {"source":"example-database","target":"http://example.org/example-database"}
  }}}
- `source` and `target` can both point at local databases, remote databases and any combination
of these.
  
  If your local CouchDB instance is secured by an admin account, you need to use the full
URL format
  
@@ -133, +145 @@

  
  === Authentication ===
  
- In some versions of CouchDB, if the remote username or password contains a special character,
CouchDB will not handle these properly. However authentication of a remote source or target
can be done manually using headers to work around the issue.
+ The remote database may require authentication, especially if it's the `target` because
the replicator will need to write to it. The easiest way to authenticate is to put a username
and password into the URL; the replicator will use these for HTTP Basic auth.
  
+ In some older versions of CouchDB, if the remote username or password contains a special
character like an `@` sign, CouchDB will not handle these properly. You can work around this
by making the `source` or `target` property an object, and adding a `headers` property to
add a custom `Authorization:` header.
+ 
- For example this will most likely not work (assuming username "bob@example.com" has password
"password"), even though the URL is properly formatted:
+ For example this may not work (assuming username "bob@example.com" has password "password"),
even though the URL is properly formatted:
  
  {{{
  POST /_replicate HTTP/1.1
@@ -143, +157 @@

  {"source":"https://bob%40example.com:password@example.net:5984/db", "target":"local-db"}
  }}}
  
- (In this case a broken CouchBD will encode the username as "bob%40example.com" instead of
"bob@example.com" when submitting authorization to the remote source.)
+ (In this case a broken CouchDB will encode the username as "bob%40example.com" instead of
"bob@example.com" when submitting authorization to the remote source.)
  
- To work around the issue, use a JSON hash as follows:
+ To work around the issue, use a JSON object for `source` or `target`, instead of a string,
as follows:
  
  {{{
  POST /_replicate HTTP/1.1
@@ -158, +172 @@

  echo -n 'bob@example.com:password' | base64
  }}}
  
- Using a JSON hash (instead of a plain string) may also be used to specify OAuth (by adding
a "oauth" field to the hash).
+ For OAuth authentication, add an `oauth` property to the `source`/`target` object. Its properties
are `consumer_secret`, `consumer_key`, `token_secret` and `token`. 
  
  == Replicator database ==
  

Mime
View raw message