This is an automated email from the ASF dual-hosted git repository.
ronny pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
The following commit(s) were added to refs/heads/main by this push:
new 0db915475 Documentation: Add `adm:pass` to replication endpoint URL
(#4457)
0db915475 is described below
commit 0db9154757a102336dc2d267370bcd23955762de
Author: Jiahui Li <[email protected]>
AuthorDate: Mon Mar 6 09:46:34 2023 -0600
Documentation: Add `adm:pass` to replication endpoint URL (#4457)
When using replication, we need to specify a username and password
(`adm:pass` / `admin:password`) for the replication endpoint URL,
otherwise a 401 unauthorized error will be thrown.
Co-authored-by: jiahuili <[email protected]>
---
src/docs/src/api/server/common.rst | 4 +-
src/docs/src/intro/api.rst | 43 +++++++++++---------
src/docs/src/replication/conflicts.rst | 8 ++--
src/docs/src/replication/replicator.rst | 70 ++++++++++++++++-----------------
4 files changed, 65 insertions(+), 60 deletions(-)
diff --git a/src/docs/src/api/server/common.rst
b/src/docs/src/api/server/common.rst
index 371511500..95478bf10 100644
--- a/src/docs/src/api/server/common.rst
+++ b/src/docs/src/api/server/common.rst
@@ -764,8 +764,8 @@
Host: localhost:5984
{
- "source": "http://127.0.0.1:5984/db_a";,
- "target": "http://127.0.0.1:5984/db_b";
+ "source": "http://adm:[email protected]:5984/db_a";,
+ "target": "http://adm:[email protected]:5984/db_b";
}
**Response**
diff --git a/src/docs/src/intro/api.rst b/src/docs/src/intro/api.rst
index f18bb5d64..3bf37c76f 100644
--- a/src/docs/src/intro/api.rst
+++ b/src/docs/src/intro/api.rst
@@ -613,8 +613,8 @@ easy to make)::
Now we can use the database `albums-replica` as a replication target::
- curl -vX POST http://admin:[email protected]:5984/_replicate \
- -d
'{"source":"http://127.0.0.1:5984/albums","target":"http://127.0.0.1:5984/albums-replica"}'
\
+ curl -X POST http://adm:[email protected]:5984/_replicate \
+ -d
'{"source":"http://adm:[email protected]:5984/albums","target":"http://adm:[email protected]:5984/albums-replica"}'
\
-H "Content-Type: application/json"
.. note::
@@ -632,22 +632,27 @@ easily):
.. code-block:: javascript
{
+ "ok": true,
+ "session_id": "30bb4ac013ca69369c0f32be78864d6e",
+ "source_last_seq":
"2-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYExlzgQLsBiaphqYpSZjKcRqRxwIkGRqA1H8Uk4wszJIskg0wdWUBAFHwJD4",
+ "replication_id_version": 4,
"history": [
{
+ "session_id": "30bb4ac013ca69369c0f32be78864d6e",
+ "start_time": "Sun, 05 Mar 2023 20:30:26 GMT",
+ "end_time": "Sun, 05 Mar 2023 20:30:29 GMT",
"start_last_seq": 0,
+ "end_last_seq":
"2-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYExlzgQLsBiaphqYpSZjKcRqRxwIkGRqA1H8Uk4wszJIskg0wdWUBAFHwJD4",
+ "recorded_seq":
"2-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYExlzgQLsBiaphqYpSZjKcRqRxwIkGRqA1H8Uk4wszJIskg0wdWUBAFHwJD4",
+ "missing_checked": 2,
"missing_found": 2,
"docs_read": 2,
- "end_last_seq": 5,
- "missing_checked": 2,
"docs_written": 2,
"doc_write_failures": 0,
- "end_time": "Sat, 11 Jul 2009 17:36:21 GMT",
- "start_time": "Sat, 11 Jul 2009 17:36:20 GMT"
+ "bulk_get_docs": 2,
+ "bulk_get_attempts": 2
}
- ],
- "source_last_seq": 5,
- "session_id": "924e75e914392343de89c99d29d06671",
- "ok": true
+ ]
}
CouchDB maintains a *session history* of replications. The response for a
@@ -660,8 +665,8 @@ replication replicates the database only as it was at the
point in time
when replication was started. So, any additions, modifications,
or deletions subsequent to the start of replication will not be replicated.
-We'll punt on the details again -- the ``"ok": true`` at the end tells us all
-went well. If you now have a look at the albums-replica database,
+We'll punt on the details again -- the ``"ok": true`` at the beginning tells
+us all went well. If you now have a look at the albums-replica database,
you should see all the documents that you created in the albums database.
Neat, eh?
@@ -676,8 +681,8 @@ and target members of our replication request are actually
links (like in
HTML) and so far we've seen links relative to the server we're working on
(hence local). You can also specify a remote database as the target::
- curl -vX POST http://admin:[email protected]:5984/_replicate \
- -d
'{"source":"http://127.0.0.1:5984/albums","target":"http://example.org:5984/albums-replica"}'
\
+ curl -X POST http://adm:[email protected]:5984/_replicate \
+ -d
'{"source":"http://adm:[email protected]:5984/albums","target":"http://user:[email protected]:5984/albums-replica"}'
\
-H "Content-Type:application/json"
Using a *local source* and a *remote target* database is called *push
@@ -695,16 +700,16 @@ You can also use a *remote source* and a *local target*
to do a *pull
replication*. This is great for getting the latest changes from a server that
is used by others::
- curl -vX POST http://admin:[email protected]:5984/_replicate \
- -d
'{"source":"http://example.org:5984/albums-replica","target":"http://127.0.0.1:5984/albums"}'
\
+ curl -X POST http://adm:[email protected]:5984/_replicate \
+ -d
'{"source":"http://user:[email protected]:5984/albums-replica","target":"http://adm:[email protected]:5984/albums"}'
\
-H "Content-Type:application/json"
Finally, you can run remote replication, which is mostly useful for management
operations::
- curl -vX POST http://admin:[email protected]:5984/_replicate \
- -d
'{"source":"http://example.org:5984/albums","target":"http://example.org:5984/albums-replica"}'
\
- -H"Content-Type: application/json"
+ curl -X POST http://adm:[email protected]:5984/_replicate \
+ -d
'{"source":"http://user:[email protected]:5984/albums","target":"http://user:[email protected]:5984/albums-replica"}'
\
+ -H "Content-Type: application/json"
.. note::
**CouchDB and REST**
diff --git a/src/docs/src/replication/conflicts.rst
b/src/docs/src/replication/conflicts.rst
index 13544830a..09468faa1 100644
--- a/src/docs/src/replication/conflicts.rst
+++ b/src/docs/src/replication/conflicts.rst
@@ -270,7 +270,7 @@ Here's how to use it to find all conflicts in a database:
.. code-block:: bash
- $ curl -X POST http://127.0.0.1/dbname/_find \
+ $ curl -X POST http://adm:[email protected]:5984/dbname/_find \
-d '{"selector": {"_conflicts": { "$exists": true}}, "conflicts":
true}' \
-Hcontent-type:application/json
@@ -289,7 +289,7 @@ index to speed the query:
.. code-block:: bash
- $ curl -X POST http://127.0.0.1/dbname/_index \
+ $ curl -X POST http://adm:[email protected]:5984/dbname/_index \
-d '{"index":{"fields": ["_conflicts"]}}' \
-Hcontent-type:application/json
@@ -307,7 +307,7 @@ to determine for each document whether it is in a
conflicting state:
.. code-block:: bash
- $ curl
'http://127.0.0.1:5984/conflict_test/_all_docs?include_docs=true&conflicts=true'
+ $ curl
'http://adm:[email protected]:5984/conflict_test/_all_docs?include_docs=true&conflicts=true'
.. code-block:: javascript
@@ -330,7 +330,7 @@ to determine for each document whether it is in a
conflicting state:
.. code-block:: bash
- $ curl 'http://127.0.0.1:5984/conflict_test/test?conflicts=true'
+ $ curl 'http://adm:[email protected]:5984/conflict_test/test?conflicts=true'
.. code-block:: javascript
diff --git a/src/docs/src/replication/replicator.rst
b/src/docs/src/replication/replicator.rst
index b06382968..65fd298f5 100644
--- a/src/docs/src/replication/replicator.rst
+++ b/src/docs/src/replication/replicator.rst
@@ -56,17 +56,17 @@ Let's say you POST the following document into
``_replicator``:
{
"_id": "my_rep",
- "source": "http://myserver.com/foo";,
+ "source": "http://user:[email protected]/foo";,
"target": {
"url": "http://localhost:5984/bar";,
"auth": {
"basic": {
- "username": "user",
+ "username": "adm",
"password": "pass"
}
}
},
- "create_target": true,
+ "create_target": true,
"continuous": true
}
@@ -181,17 +181,17 @@ For example, POST-ing this document
{
"_id": "my_rep_crashing",
- "source": "http://myserver.com/missing";,
+ "source": "http://user:[email protected]/missing";,
"target": {
"url": "http://localhost:5984/bar";,
"auth": {
"basic": {
- "username": "user",
+ "username": "adm",
"password": "pass"
}
}
},
- "create_target": true,
+ "create_target": true,
"continuous": true
}
@@ -252,16 +252,16 @@ normal.
Documents describing the same replication
=========================================
-Lets suppose 2 documents are added to the ``_replicator`` database in
+Let's suppose 2 documents are added to the ``_replicator`` database in
the following order:
.. code-block:: javascript
{
"_id": "my_rep",
- "source": "http://myserver.com/foo";,
- "target": "http://user:pass@localhost:5984/bar";,
- "create_target": true,
+ "source": "http://user:[email protected]/foo";,
+ "target": "http://adm:pass@localhost:5984/bar";,
+ "create_target": true,
"continuous": true
}
@@ -271,9 +271,9 @@ and
{
"_id": "my_rep_dup",
- "source": "http://myserver.com/foo";,
- "target": "http://user:pass@localhost:5984/bar";,
- "create_target": true,
+ "source": "http://user:[email protected]/foo";,
+ "target": "http://adm:pass@localhost:5984/bar";,
+ "create_target": true,
"continuous": true
}
@@ -517,34 +517,34 @@ which represent pull replications from servers A and B:
{
"_id": "rep_from_A",
- "source": "http://aserver.com:5984/foo";,
+ "source": "http://user:[email protected]:5984/foo";,
"target": {
"url": "http://localhost:5984/foo_a";,
"auth": {
"basic": {
- "username": "user",
+ "username": "adm",
"password": "pass"
}
}
},
- "continuous": true
+ "continuous": true
}
.. code-block:: javascript
{
"_id": "rep_from_B",
- "source": "http://bserver.com:5984/foo";,
+ "source": "http://user:[email protected]:5984/foo";,
"target": {
"url": "http://localhost:5984/foo_b";,
"auth": {
"basic": {
- "username": "user",
+ "username": "adm",
"password": "pass"
}
}
},
- "continuous": true
+ "continuous": true
}
Now without stopping and restarting CouchDB, add another replicator
@@ -552,11 +552,11 @@ database. For example ``another/_replicator``:
.. code-block:: bash
- $ curl -X PUT http://user:pass@localhost:5984/another%2F_replicator/
+ $ curl -X PUT http://adm:pass@localhost:5984/another%2F_replicator/
{"ok":true}
.. note::
- A / character in a database name, when used in a URL, should be escaped.
+ A ``/`` (%2F) character in a database name, when used in a URL, should be
escaped.
Then add a replication document to the new replicator database:
@@ -564,9 +564,9 @@ Then add a replication document to the new replicator
database:
{
"_id": "rep_from_X",
- "source": "http://xserver.com:5984/foo";,
- "target": "http://user:pass@localhost:5984/foo_x";,
- "continuous": true
+ "source": "http://user:[email protected]:5984/foo";,
+ "target": "http://adm:pass@localhost:5984/foo_x";,
+ "continuous": true
}
From now on, there are three replications active in the system: two
@@ -576,7 +576,7 @@ Then remove the additional replicator database:
.. code-block:: bash
- $ curl -X DELETE http://user:pass@localhost:5984/another%2F_replicator/
+ $ curl -X DELETE http://adm:pass@localhost:5984/another%2F_replicator/
{"ok":true}
After this operation, replication pulling from server X will be stopped
@@ -633,18 +633,18 @@ following pull replication documents in it:
{
"_id": "rep_from_A",
- "source": "http://aserver.com:5984/foo";,
- "target": "http://user:pass@localhost:5984/foo_a";,
- "continuous": true
+ "source": "http://user:[email protected]:5984/foo";,
+ "target": "http://adm:pass@localhost:5984/foo_a";,
+ "continuous": true
}
.. code-block:: javascript
{
"_id": "rep_from_B",
- "source": "http://bserver.com:5984/foo";,
- "target": "http://user:pass@localhost:5984/foo_b";,
- "continuous": true
+ "source": "http://user:[email protected]:5984/foo";,
+ "target": "http://adm:pass@localhost:5984/foo_b";,
+ "continuous": true
}
Now you would like to have the same pull replications going on in server
@@ -697,9 +697,9 @@ Example delegated replication document:
{
"_id": "my_rep",
- "source": "http://bserver.com:5984/foo";,
- "target": "http://user:pass@localhost:5984/bar";,
- "continuous": true,
+ "source": "http://user:[email protected]:5984/foo";,
+ "target": "http://adm:pass@localhost:5984/bar";,
+ "continuous": true,
"user_ctx": {
"name": "joe",
"roles": ["erlanger", "researcher"]
@@ -770,7 +770,7 @@ There are multiple ways to specify usernames and passwords
for replication endpo
.. code-block:: javascript
{
- "target": "http://user:pass@localhost:5984/bar";
+ "target": "http://adm:pass@localhost:5984/bar";
...
}
