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 "[email protected]" has password "password"), even though the URL is properly formatted: + For example this may not work (assuming username "[email protected]" has password "password"), even though the URL is properly formatted: {{{ POST /_replicate HTTP/1.1 @@ -143, +157 @@ {"source":"https://bob%40example.com:[email protected]:5984/db";, "target":"local-db"} }}} - (In this case a broken CouchBD will encode the username as "bob%40example.com" instead of "[email protected]" when submitting authorization to the remote source.) + (In this case a broken CouchDB will encode the username as "bob%40example.com" instead of "[email protected]" 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 '[email protected]: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 ==
