Share Your Data Using Couchdb Replication
Experimental Feature
This feature may be removed or changed in the future. It might also have unhandled cases and cause corruption in your data. Be sure to backup your data constantly while using this.
Advanced Functionality
You're recommended to have some background knowledge about CouchDB before doing this.
Thanks to the power of CouchDB, sharing your whole database or parts of your data with another user can be easily done with CouchDB Replication, with the following use cases supported:
Share items only in specific collections.
Share items by custom rules.
Share with read-only access.
Share with read-write access.
However, it has the following limitations:
One user must give their CouchDB database access to the other user, which means it's possible that a user can see or change everything in the other user's database.
The people you shared your data with won't be able to change the Reference Number of your collection and items.
If you set a Two-way Replication (Read-write Sharing), the person with whom you share your data with might be able to mess up with your unshared data if they know it's ID.
Prerequisite
Both you and the one you want to share data with must have CouchDB sync setup. The two CouchDB databases aren't required to be on the same server, but they should be reachable to one another.
Setup a One-way Replication - For Read-only Sharing
You'll need to create a replication document in the _replicator
database on one of the servers. Here's a sample:
You can copy the JSON document above and paste it into the editor in http(s)://<your_couchdb_server>:<port>/_utils/#database/_replicator/_new
(e.g. http://127.0.0.1:5984/_utils/#database/_replicator/_new).
Note that you'll need to change some of the fields in your document:
_id
: You can choose a recognizable ID for your replication. It should be unique.source
: Set the connection of the source database, i.e., the database storing the items to be shared.For the Authorization field, encode the username and password as
username:password
with Base64. For example, by runningprint -n 'example:password' | base64
in *nix.
target
: Set the connection of the target database, i.e., the database that you want to share the items with.selector
: Use this to share every collection and item or specific collections and items. See examples below. This MUST be set to at least{ "$or": [{ "type": "collection" }, { "type": "item" }] }
to prevent overwriting everything in the target database. For more info, see https://docs.couchdb.org/en/stable/api/database/find.html#selector-syntax.
For more info, see https://docs.couchdb.org/en/stable/json-structure.html#replication-settings.
After saving the replication, you can see its status at http(s)://<your_couchdb_server>:<port>/_utils/#/replication
(e.g. http://127.0.0.1:5984/_utils/#/replication).
Selector Examples
https://docs.couchdb.org/en/stable/replication/intro.html#controlling-which-documents-to-replicate asdf
Setup a Two-way Replication - For Read-write Sharing
Create a replication document the same as Setup a One-way Replication.
Create another replication document with the same content as step 1 but with the
source
andtarget
databases swapped.Ask the person you want to share data with for their Configuration UUID. The Configuration UUID can be found in the app (More -> Settings -> Configurations).
Create a document in your source database with
_id
set todb_sharing-<your_config_uuid>--<their_config_uuid>
, as follows:
Note: This document will not actually permit one to write into your database. It will just unblock the UI for editing.
Edit the replication document you created on step 1, and add the ID of step 4 to the
selector
section. For example:
How to stop sharing?
Delete the
db_sharing-<your_config_uuid>--<their_config_uuid>
document in your database, if you had created one.Remove the corresponding replications from the
_replicator
database.Optionally, ask the person you shared data with to purge the documents that came from your database from their own database. Note: do not use delete, since the deletion will be replicated back to your database if you do replication from their database again.
Troubleshooting
Last updated
Was this helpful?