=======================
ech - Embedded CouchDB
=======================

What and Why
============

ech is an Erlang library that provides a simple interface for using CouchDB
as an embeddable database within your Erlang application.

It is fundamentally different from Erlang clients that interface with
CouchDB over HTTP.

Here's how you'd use it:

  1> {ok, Db} = ech:open("test").
  2> Doc = ech_doc:new("chi", [{name, "Chicago"}, {type, "city"}]).
  3> ech:put(Db, Doc).
  4> {ok, Loaded} = ech:get(Db, "chi").
  5> ech_doc:get_attrs(Loaded).
  [{type,"city"},{name,"Chicago"}]

You might want to work with an embedded database instead of a CouchDB over
HTTP for these reasons:

- You want a simple, scalable, performant data store that is part of your
  application and doesn't have to be installed and managed separately

- You want to build your own distributed database and want to leverage
  CouchDB's outstanding b-tree indexing, lazy indexing, and replication
  support

- The idea of unnecessarily forcing Erlang through a JSON/HTTP layer offends
  your sense of economy

Getting Started
===============

Get the source for CouchDB and note its root directory, which is used as
COUCH_HOME below.

Get the ech source from github.

At a console prompt:

 $ cd ech
 $ export COUCH_HOME=<dir>
 $ make

Running Tests
=============

 $ make TESTS=ech_tests test

Using ech
=========

Refer to ECH_HOME/lib/ech/src/ech_tests.erl for examples.

You can experiment with ech from an Erlang shell by running:

 $ make shell

Installing ech
==============

We're working on this. Until something better is available, you can simply
include ETCH_HOME in the ERL_LIBS environment variable when running your
application. E.g.

 $ ERL_LIBS=<ech home dir> erl