tor-async-couchdb is a Tornado async client for CouchDB. tor-async-couchdb is intended to operate as part of a service's application tier and interact with the service's data tier implemented using CouchDB.

tor-async-couchdb documentation isn't as strong as it could be. This README.md, samples and tests are best way to gain an understanding of how to use tor-async-couchdb.

tor-async-couchdb was originally created for use with CouchDB. tor-async-couchdb has also been used with Cloudant DBaaS and Cloudant Local.

tor-async-couchdb was created as a way to capture the best practices learned after operating and scaling a number of services that used CouchDB and Tornado. The bullets below summarize these best practices.

• services should embrace eventual consistency
• thoughts on data models:
  • every document should have a versioned type property (ex type=v9.99)
  • documents are chunky; retrieval of a single document is often all that's necessary to implement a RESTful service's endpoint ala standard NoSQL data model thinking
  • assume conflicts happen as part of regular operation
  • sensitive data at rest is an information security concern; each property should be evaluated against a data and information classification policy; if a property is deemed sensitive it should, ideally, be hashed ([bcrypt](py-bcrypt preferred and if not SHA3-512); if a sensitive property can't be hashed it should be encrypted using Keyczar - this is a good example of data classification
• CouchDB, not the service tier, should generate document IDs
• document retrieval should be done through views against document properties not document IDs
• one design document per view
• horizontally scaling CouchDB should be done using infrastructure (CouchDB 2.0 and Cloudant) not application level sharding
• direct tampering of data in the database by DBAs is undesirable and therefore tamper resistance is valued

Add the following to your project's setup.py:

from setuptools import setup
setup(
    install_requires=[
        "tor-async-couchdb==0.30.0",
    ],
    dependency_links=[
        "https://github.com/simonsdave/tor-async-couchdb/tarball/v0.30.0#egg=tor-async-couchdb-0.30.0",
    ],

Configure tor-async-couchdb in your service's mainline. Typically the configuration options are expected to come from a configuration file and/or the service's command line.

from tor_async_couchdb import async_model_actions

async_model_actions.database = "http://127.0.0.1:5984/database"
async_model_actions.tampering_signer = None
async_model_actions.username = None
async_model_actions.password = None
async_model_actions.validate_cert = True