CouchDB Database & User Functions

CouchDB Database & User Functions

Even though CouchDB has been added as an experimental datastore in Trove, the functionality yet has some gaps to be filled. The motivation behind this spec is to implement some of those missing user and database functions for the CouchDB datastore in Trove.

Launchpad Blueprint:

Problem Description

Currently, a CouchDB instance can be created using Trove but the functionality is very limited. No user or database actions can be performed via the Trove CLI. While, it is possible to perform such operations by accessing the CouchDB administration interface called Futon 1, it is not within the scope of Trove. Therefore for ease of use and consistency, it is best that these database and user functionalities for CouchDB be implemented as part of Trove.

Proposed Change

Implementation of the basic user and database functions will be performed for the CouchDB datastore in Trove using an HTTP-based REST API which CouchDB uses to communicate with the server. Curl commands will be sent over HTTP requests to the CouchDB server which will then execute actions.

The new operations that will be supported are as follows:

  • create/delete/show user

  • list users

  • grant/revoke/show access

  • root enable/show

  • create/delete database

  • list databases

A CouchDBAdmin class will be created in which will have these methods in it and the functions in will be updated to call these new methods. Each method will use the core CouchDB API to make appropriate HTTP requests for that functionality on the server.

As of now an API extension for CouchDB does not exist so a new API extension will be created to implement datastore specifics while moderating user/ database operations. The validation in effect in the CouchDB specific models will correspond to CouchDB datastore requirements.

CouchDB Security

On a fresh CouchDB instance, the server allows any request to be made by anyone - it’s an Admin Party 2 . To enable the user functionalities, the guest agent’s CouchDB server will be made secure by creating a Trove user ‘os_admin’ by default. When a guest is first started, the os_admin user will be created and will be connected to the server using a password generated by the guest. This will be done using the following command- curl -X PUT http://localhost:5984/_config/admins/os_admin -d '"password"'

The username and generated password will be stored in a file in the home ~ directory on the instance (stream_codecs.JsonCodec will be used to handle it). All other users that are created are non-admin users so this preventing anybody from accidentally creating an admin user 3 . The only admin user that can be created is ‘root’ using the trove root-enable command by creating a user on the couchDB server with admin privileges.





Public API

The user will be able to run the implemented functions for CouchDB datastore via CLI.

Public API Security


Python API


CLI (python-troveclient)

The following Trove command line commands will be functional for CouchDB:

  • trove user-create

  • trove user-delete

  • trove user-grant-access

  • trove user-list

  • trove user-revoke-access

  • trove user-show

  • trove user-show-access

  • trove root-enable

  • trove root-show

  • trove database-create

  • trove database-delete

  • trove database-list

Internal API


Guest Agent

The CouchDB guest agent will be modified to support additional database and user functionality. In particular the following files will have added components:


Several new guest agent functions will be implemented using the CouchDB API. Below are sample API calls and associated details for each guest agent method.


Create non-admin user with name username and password password

curl -X PUT http://os_admin:password@localhost:5984/_users/org.couchdb
.user:username \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name": "username", "password": "password", "roles": [], "type":


List all the users from the system database _users and all the databases from the system database _all_dbs. Then cross reference to list users and the databases that they have access to.

curl -s http://os_admin:password@localhost:5984/_users/_all_docs

curl -X http://os_admin:password@localhost:5984/_all_dbs

curl -X http://os_admin:password@localhost:5984/databasename/_security


Deletes user username from the system database _users corresponding to rev number 1-3cd11775d7e3ba15a9f8c553cb3d47bd. The rev number for the document to be obtained using the second command listed below.

curl -X DELETE http://os_admin:password@localhost:5984/_users/org. couchdb.user:username?rev=1-3cd11775d7e3ba15a9f8c553cb3d47bd

curl -s http://os_admin:password@localhost:5984/_users/_all_docs


Shows the complete information associated with a specific user - username, databases user has access to and permissions(admin/member).

curl -X http://os_admin:password@localhost:5984/_all_dbs

curl -X http://os_admin:password@localhost:5984/databasename/_security


Create user “root” and grant the role “admin”

curl -X PUT http://os_admin:password@localhost:5984/_config/admins/
root -d '"password"'


Checks if user root exists in the system database _config and has admin privileges

curl -s http://os_admin:password@localhost:5984/_config/_admins


Deletes the root user from the CouchDB instance.

curl -X DELETE http://


Modify the role of user username for database databasename to include username as a listed admin

curl -X PUT http://os_admin:password@localhost:5984
/databasename/_security \
> -d '{"admins":{"names":[], "roles":[]}, "members":{"names”:[


Similar to the implementation of grant access, modify the role of user ` username`` for database databasename to remove username as a listed member

curl -X PUT http://os_admin:password@localhost:5984
/databasename/_security \
> -d '{"admins":{"names":[], "roles":[]}, "members":{"names”:[],


Lists all the databases from the system database _all_dbs. Then cross reference to list all the databases that the specified user has has access to.

curl -X http://os_admin:password@localhost:5984/_all_dbs

curl -X http://os_admin:password@localhost:5984/databasename/_security


Creates a database with name database_name

curl -X PUT http://os_admin:password@localhost:5984/database_name

The database name must consist of one or more of the following characters and the name must begin with a lowercase letter 4 .

  • Lowercase characters (a-z)

  • Digits (0-9)

  • Any of the characters _, $, (, ), +, -, and /.


Deletes the database with name database_name

curl -X DELETE http://os_admin:password@localhost:5984/database_name


Lists all the databases from the system database _all_dbs

curl -X GET http://os_admin:password@localhost:5984/_all_dbs



Dashboard Impact (UX)

The dashboard will need to be updated for the users and databases tabs to be enabled for the CouchDB datastore. No new features will need to be added to the dashboard.



Primary assignee:

imandhan (launchpad id) Ishita Mandhan <>



Work Items

Implementation of the functionality of user and database functions for CouchDB. Involves working on the manager, service and system files primarily. Tests will be written as required - both unit tests and int tests. The work will be split into 5 parts-

  1. Enable authentication on server

  2. Create/delete/get/list user

  3. Enable/check root

  4. grant/revoke/list access

  5. create/delete/list database

Upgrade Implications





Unit tests and integration tests will be added as necessary to test new code added.

Documentation Impact

The CouchDB Trove documentation will need to be updated to indicate that user and database functions have been implemented.



Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

trove-specs 0.0.1.dev177