Update local replication documentation (#423)
* Update replication docs to use fully qualified URLs
* Update local replication examples
* Add note calling attention to the new fully-qualified URL requirement
* Document _replicate transformation ability
Co-authored-by: Joan Touzet <wohali@users.noreply.github.com>
diff --git a/src/api/server/common.rst b/src/api/server/common.rst
index df84330..415e45f 100644
--- a/src/api/server/common.rst
+++ b/src/api/server/common.rst
@@ -602,16 +602,22 @@
:<json string target_proxy: Address of a proxy server through which
replication to the target should occur (protocol can be "http" or
"socks5")
- :<json string/object source: Source database name or URL or an object
- which contains the full URL of the source database with additional
- parameters like headers. Eg: 'source_db_name' or
- 'http://example.com/source_db_name' or
- {"url":"url in here", "headers": {"header1":"value1", ...}}
- :<json string/object target: Target database name or URL or an object
- which contains the full URL of the target database with additional
- parameters like headers. Eg: 'target_db_name' or
- 'http://example.com/target_db_name' or
- {"url":"url in here", "headers": {"header1":"value1", ...}}
+ :<json string/object source: Fully qualified source database URL or an
+ object which contains the full URL of the source database with additional
+ parameters like headers. Eg: 'http://example.com/source_db_name' or
+ {"url":"url in here", "headers": {"header1":"value1", ...}} . For
+ backwards compatibility, CouchDB 3.x will auto-convert bare database
+ names by prepending the address and port CouchDB is listening on, to
+ form a complete URL. This behaviour is deprecated in 3.x and will be
+ removed in CouchDB 4.0.
+ :<json string/object target: Fully qualified target database URL or an
+ object which contains the full URL of the target database with additional
+ parameters like headers. Eg: 'http://example.com/target_db_name' or
+ {"url":"url in here", "headers": {"header1":"value1", ...}} . For
+ backwards compatibility, CouchDB 3.x will auto-convert bare database
+ names by prepending the address and port CouchDB is listening on, to
+ form a complete URL. This behaviour is deprecated in 3.x and will be
+ removed in CouchDB 4.0.
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:>json array history: Replication history (see below)
@@ -648,19 +654,23 @@
:json string start_time: Date/Time replication operation started in
:rfc:`2822` format
+.. note::
+ As of CouchDB 2.0.0, fully qualified URLs are required for both the
+ replication `source` and `target` parameters.
+
**Request**
.. code-block:: http
POST /_replicate HTTP/1.1
Accept: application/json
- Content-Length: 36
+ Content-Length: 80
Content-Type: application/json
Host: localhost:5984
{
- "source": "db_a",
- "target": "db_b"
+ "source": "http://127.0.0.1:5984/db_a",
+ "target": "http://127.0.0.1:5984/db_b"
}
**Response**
diff --git a/src/intro/api.rst b/src/intro/api.rst
index 82e067b..04aaa76 100644
--- a/src/intro/api.rst
+++ b/src/intro/api.rst
@@ -605,10 +605,14 @@
Now we can use the database `albums-replica` as a replication target::
curl -vX POST http://127.0.0.1:5984/_replicate \
- -d '{"source":"albums","target":"albums-replica"}' \
+ -d '{"source":"http://127.0.0.1:5984/albums","target":"http://127.0.0.1:5984/albums-replica"}' \
-H "Content-Type: application/json"
.. note::
+ As of CouchDB 2.0.0, fully qualified URLs are required for both the
+ replication `source` and `target` parameters.
+
+.. note::
CouchDB supports the option ``"create_target":true`` placed in the JSON
POSTed to the :ref:`_replicate <api/server/replicate>` URL. It implicitly
creates the target database if it doesn't exist.
@@ -664,7 +668,7 @@
(hence local). You can also specify a remote database as the target::
curl -vX POST http://127.0.0.1:5984/_replicate \
- -d '{"source":"albums","target":"http://example.org:5984/albums-replica"}' \
+ -d '{"source":"http://127.0.0.1:5984/albums","target":"http://example.org:5984/albums-replica"}' \
-H "Content-Type:application/json"
Using a *local source* and a *remote target* database is called *push
@@ -683,7 +687,7 @@
is used by others::
curl -vX POST http://127.0.0.1:5984/_replicate \
- -d '{"source":"http://example.org:5984/albums-replica","target":"albums"}' \
+ -d '{"source":"http://example.org:5984/albums-replica","target":"http://127.0.0.1:5984/albums"}' \
-H "Content-Type:application/json"
Finally, you can run remote replication, which is mostly useful for management
