Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A CouchDB Clustering Proxy. (Actually, it's a reverse proxy, a.k.a. gateway.)
Erlang Shell
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
config
deps
priv/www
src
support
.gitignore
LICENSE
Makefile
README.md
start-dev.sh
start.sh

README.md

CouchDBCP

Abstract

CouchDBCP is an acronym for CouchDB Clustering Proxy. Basically, it's a reverse proxy (a.k.a. gateway) for maintaining CouchDB clusters. Its objective is to allow for an abstraction of a single reliable CouchDB device, using a collection of possibly unreliable CouchDB units.

Motivation

The initial motivation for CouchDBCP was to have a solution for managing CouchDB nodes in a decentralized way, so that one can have control over the consistency level and replication behavior. Imagine you have an application scenario that requires atomic data consistency in favor of availability just for a small subset of your data. Wouldn't it be cool, being able to control the consistency level on a per-request basis?

Description

As of now, CouchDBCP does not support data partitioning. It can only be used to manage redundant CouchDB instances in a decentralized way. As long as data partitioning is not available, it is intended that each CouchDBCP is assigned only one CouchDB node. A CouchDBCP is used as a gateway (more precisely as a reverse HTTP proxy) in front of a CouchDB. In order to minimize latency, the two components are intended to be located nearby, connected with a high speed, low-latency network link; if not just simply located on the same computer.

Currently, most Futon tests are passing. Some are failing because the REST constraint of stateless communication is violated. Furthermore, there are a few tests that sometimes fail due to timeouts when the CouchDB instances are frequently restarted by the test. There should be room for improvement regarding socket communication, timeouts and error handling.

Regarding cookie authentication, CouchDBCP is currently able to maintain authentication state: If atomic consistency is used for cookie authentication (i.e., the POST request to /_session), it is possible to load-balance requests over all cluster nodes, without losing authentication.

Future Goals

Future goals are:

  • decentralized cluster configuration using an HTTP-based gossip protocol
  • data partitioning support based on consistent hashing (c.f. riak_core)
  • cluster monitoring

Version

Version 0.2 - 2010-08-09

Version History

Version 0.2 - 2010-08-09 - Fixed Makefile. After checking out, make failed because the ebin directory was missing. - Removed header_cache. It doesn't work out. - Eventual consistency (in favor of availability) is also supported for write operations now. - Established automatic conflict resolution.

Version 0.1 - 2010-08-02 - Initial version.

Dependencies

CouchDBCP depends on MochiWeb and ibrowse. Make sure that these libraries are available on your system.

Installation

Compilation

To compile CouchDBCP, simply run make. At this point in time, there is no install target. For compilation, MochiWeb and ibrowse (see Dependencies) are expected to be located in CouchDBCP's parent directory. If the libraries are located elsewhere, you need to set the symbolic links in deps accordingly.

Configuration

CouchDBCP's configuration is done in config/couchdbcp.erlenv. Logging is configured in config/elog.config.

See the included sample configuration.

Usage

Launching CouchDBCP

There are two scripts included to launch CouchDBCP: one for development (start-dev.sh), and one for a production environment (start.sh). To launch CouchDBCP, the first argument you need to specify is a yet unused node name (that is specified in the configuration file config/couchdbcp.erlenv). The second argument is the configuration file itself, e.g.:

./start-dev.sh proxy-1@127.0.0.11 config/couchdbcp.erlenv

Of course, you also need to make sure that the CouchDB instance assigned to the respective CouchDBCP is up.

Consistency Semantics

CouchDBCP supports two different data consistency levels to be set in the configuration file (config/couchdbcp.erlenv). However, the configured consistency level can be overridden on a per-request basis, simply by setting one of the following custom HTTP request headers:

  • X-CouchDBCP-Consistency: atomic
  • X-CouchDBCP-Consistency: eventual

Contributors

  • Klaus Trainer - original author
  • You! Come on...
Something went wrong with that request. Please try again.