Skip to content
This repository was archived by the owner on Oct 17, 2022. It is now read-only.

Remove configurable replicator db name functionality #41

Merged
merged 1 commit into from
Mar 2, 2016
Merged

Remove configurable replicator db name functionality #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 0 additions & 7 deletions src/config/replicator.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,6 @@ Replicator Database Configuration

.. versionadded:: 1.2

.. config:option:: db

Specifies replicator database name::

[replicator]
db = _replicator

.. config:option:: max_replication_retry_count

Maximum replication retry count can be a non-negative integer or
Expand Down
84 changes: 39 additions & 45 deletions src/replication/replicator.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,9 @@ Replication documents can have a user defined ``_id`` (handy for finding a
specific replication request later). Design Documents (and ``_local`` documents)
added to the replicator database are ignored.

The default name of this database is ``_replicator``. The name can be changed in
the ``local.ini`` configuration, section ``[replicator]``, parameter ``db``.
The default name of this database is ``_replicator``. Additional replicator
databases can be created. To be recognized as such by the system, their database
names should end with ``/_replicator``.

Basics
======
Expand All @@ -43,7 +44,7 @@ Let's say you POST the following document into ``_replicator``:
{
"_id": "my_rep",
"source": "http://myserver.com:5984/foo",
"target": "bar",
"target": "http://user:pass@localhost:5984/bar",
"create_target": true
}

Expand All @@ -62,7 +63,7 @@ CouchDB with 3 new fields:
{
"_id": "my_rep",
"source": "http://myserver.com:5984/foo",
"target": "bar",
"target": "http://user:pass@localhost:5984/bar",
"create_target": true,
"_replication_id": "c0ebe9256695ff083347cbf95f93e280",
"_replication_state": "triggered",
Expand Down Expand Up @@ -96,12 +97,12 @@ Special fields set by the replicator start with the prefix
{
"_id": "my_rep",
"_rev": "2-9f2c0d9372f4ee4dc75652ab8f8e7c70",
"source": "foodb",
"target": "bardb",
"source": "http://myserver.com:5984/foo",
"target": "http://user:pass@localhost:5984/bar",
"_replication_state": "error",
"_replication_state_time": "2013-12-13T18:48:00+01:00",
"_replication_state_reason": "db_not_found: could not open foodb",
"_replication_id": "fe965cdc47b4d5f6c02811d9d351ac3d"
"_replication_id": "c0ebe9256695ff083347cbf95f93e280"
}

When the replication finishes, it will update the ``_replication_state``
Expand All @@ -113,7 +114,7 @@ the document will look like:
{
"_id": "my_rep",
"source": "http://myserver.com:5984/foo",
"target": "bar",
"target": "http://user:pass@localhost:5984/bar",
"create_target": true,
"_replication_id": "c0ebe9256695ff083347cbf95f93e280",
"_replication_state": "completed",
Expand Down Expand Up @@ -156,7 +157,7 @@ the following order:
{
"_id": "doc_A",
"source": "http://myserver.com:5984/foo",
"target": "bar"
"target": "http://user:pass@localhost:5984/bar"
}

and
Expand All @@ -166,7 +167,7 @@ and
{
"_id": "doc_B",
"source": "http://myserver.com:5984/foo",
"target": "bar"
"target": "http://user:pass@localhost:5984/bar"
}

Both describe exactly the same replication (only their ``_ids`` differ). In this
Expand All @@ -181,7 +182,7 @@ look like this:
{
"_id": "doc_B",
"source": "http://myserver.com:5984/foo",
"target": "bar",
"target": "http://user:pass@localhost:5984/bar",
"_replication_id": "c0ebe9256695ff083347cbf95f93e280"
}

Expand All @@ -192,7 +193,7 @@ While document ``doc_A`` will look like this:
{
"_id": "doc_A",
"source": "http://myserver.com:5984/foo",
"target": "bar",
"target": "http://user:pass@localhost:5984/bar",
"_replication_id": "c0ebe9256695ff083347cbf95f93e280",
"_replication_state": "triggered",
"_replication_state_time": 1297974122
Expand Down Expand Up @@ -247,18 +248,18 @@ to do this will result in the following response
The way to accomplish this is to first delete the old version and then insert
the new one.

Changing the Replicator Database
Additional Replicator Databases
================================

Imagine your replicator database (default name is ``_replicator``) has the two
following documents that represent pull replications from servers A and B:
Imagine replicator database (``_replicator``) has these two
documents which represent pull replications from servers A and B:

.. code-block:: javascript

{
"_id": "rep_from_A",
"source": "http://aserver.com:5984/foo",
"target": "foo_a",
"target": "http://user:pass@localhost:5984/foo_a",
"continuous": true,
"_replication_id": "c0ebe9256695ff083347cbf95f93e280",
"_replication_state": "triggered",
Expand All @@ -270,55 +271,48 @@ following documents that represent pull replications from servers A and B:
{
"_id": "rep_from_B",
"source": "http://bserver.com:5984/foo",
"target": "foo_b",
"target": "http://user:pass@localhost:5984/foo_b",
"continuous": true,
"_replication_id": "231bb3cf9d48314eaa8d48a9170570d1",
"_replication_state": "triggered",
"_replication_state_time": 1297974122
}

Now without stopping and restarting CouchDB, you change the name of the
replicator database to ``another_replicator_db``:
Now without stopping and restarting CouchDB, add another replicator database.
For example ``another/_replicator``:

.. code-block:: bash

$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"'
"_replicator"

As soon as this is done, both pull replications defined before, are
stopped. This is explicitly mentioned in CouchDB's log:

.. code-block:: text
$ curl -X PUT http://user:pass@localhost:5984/another%2F_replicator/
{"ok":true}

[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.104.0>] Stopping all ongoing replications because the replicator database was deleted or changed
[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.127.0>] 127.0.0.1 - - PUT /_config/replicator/db 200
.. note::
A / character in a database name, when used in a URL, should be escaped.

Imagine now you add a replication document to the new replicator
database named ``another_replicator_db``:
Then add a replication document to the new replicator database:

.. code-block:: javascript

{
"_id": "rep_from_X",
"source": "http://xserver.com:5984/foo",
"target": "foo_x",
"target": "http://user:pass@localhost:5984/foo_x",
"continuous": true
}

From now own you have a single replication going on in your system: a
pull replication pulling from server X. Now you change back the
replicator database to the original one ``_replicator``::
From now on, there are three replications active in the system: two replications
from A and B, and a new one from X.

Then remove the additional replicator database:

$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"'
"another_replicator_db"
.. code-block:: bash

Immediately after this operation, the replication pulling from server X
will be stopped and the replications defined in the ``_replicator``
database (pulling from servers A and B) will be resumed.
$ curl -X DELETE http://user:pass@localhost:5984/another%2F_replicator/
{"ok":true}

Changing again the replicator database to ``another_replicator_db`` will
stop the pull replications pulling from servers A and B, and resume the
pull replication pulling from server X.
After this operation, replication pulling from server X
will be stopped and the replications in the ``_replicator``
database (pulling from servers A and B) will continue.

Replicating the replicator database
===================================
Expand All @@ -331,7 +325,7 @@ following pull replication documents in it:
{
"_id": "rep_from_A",
"source": "http://aserver.com:5984/foo",
"target": "foo_a",
"target": "http://user:pass@localhost:5984/foo_a",
"continuous": true,
"_replication_id": "c0ebe9256695ff083347cbf95f93e280",
"_replication_state": "triggered",
Expand All @@ -343,7 +337,7 @@ following pull replication documents in it:
{
"_id": "rep_from_B",
"source": "http://bserver.com:5984/foo",
"target": "foo_b",
"target": "http://user:pass@localhost:5984/foo_b",
"continuous": true,
"_replication_id": "231bb3cf9d48314eaa8d48a9170570d1",
"_replication_state": "triggered",
Expand Down Expand Up @@ -402,7 +396,7 @@ Example delegated replication document:
{
"_id": "my_rep",
"source": "http://bserver.com:5984/foo",
"target": "bar",
"target": "http://user:pass@localhost:5984/bar",
"continuous": true,
"user_ctx": {
"name": "joe",
Expand Down
6 changes: 6 additions & 0 deletions src/whatsnew/2.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,12 @@ Upgrade Notes

.. note:: TBD

* It is possible to have multiple replicator databases.
`replicator/db` config option has been removed.
Instead `_replicator` and any database names ending
with `/_replicator` suffix will be recognized as
replicator databases by the system.

.. _release/2.0.0:

Version 2.0.0
Expand Down