Hex pm Build Status License

Erlang / Elixir library for Apache CouchDB or IBM Cloudant. CouchDB provides you a full featured and easy-to-use client to access and manage multiple nodes.


Most of the Erlang/Elixir CouchDB API takes Database or Server record as an argument. This record contains information about the server's FQDN, the database name, etc. Parts of the API dealing with 'the server' will take a server record, while functions performing actions on databases and documents take a database record. Consider:

{ok, Server} = couchdb:server_record(<<"http://localhost:5984">>, []).

{:ok, server} = :couchdb.server_record("http://localhost:5984", [])

After a server or database record has been created one can now make the first actual call:

{ok, Info} = couchdb_server:info(Server).

{:ok, info} =


For issues, comments or feedback please create an issue.


Forked from Couchbeam

CouchDB is a a fork of couchbeam

Semantic versioning

To comply with Semantic Versioning the version number has been bumped to 2.0.0.

New uuid implementation

In Beta6 the original Apache CouchDB uuid implementation was added.

Original README:

Couchbeam - simple Barrel and Apache CouchDB client library for Erlang applications


Couchbeam is a simple erlang library for Barrel or Apache CouchDB. Couchbeam provides you a full featured and easy client to access and manage multiple nodes.

Main features:

Useful modules are:

The goal of Couchbeam is to ease the access to the Apache CouchDB and RCOUCH HTTP API in erlang.

Read the NEWS file to get last changelog.


Download the sources from our Github repository

To build the application simply run 'make'. This should build .beam, .app files and documentation.

To run tests run 'make test'. To generate doc, run 'make doc'.

Or add it to your rebar config

{deps, [

{couchbeam, ".*", {git, "git://", {branch, "master"}}}



Note to compile with jiffy you need to define in the erlang options the variable WITH_JIFFY.

if you use rebar, add to your rebar.config:

{erlopts, [{d, 'WITHJIFFY'}]}.

or use the rebar command with the -D options:

rebar compile -DWITH_JIFFY

Basic Usage

Start couchbeam

Couchbeam is an OTP application. You have to start it first before using any of the functions. The couchbeam application will start the default socket pool for you.

To start in the console run:

$ erl -pa ebin
1> couchbeam:start().

It will start hackney and all of the application it depends on:


Or add couchbeam to the applications property of your .app in a release

Create a connection to the server

To create a connection to a server machine:

Url = "http://localhost:5984",
Options = [],
S = couchbeam:server_connection(Url, Options).

Test the connection with couchbeam:server_info/1 :

{ok, Version} = couchbeam:serverinfo(S).

Open or Create a database

All document operations are done in databases. To open a database simply do:

Options = [],
{ok, Db} = couchbeam:open_db(Server, "testdb", Options).

To create a new one:

Options = [],
{ok, Db} = couchbeam:create_db(Server, "testdb", Options).

You can also use the shorcut couchbeam:openorcreate_db/3. that will create a database if it does not exist.

Make a new document

Make a new document:

Doc = {[
{<<"_id">>, <<"test">>},
{<<"content">>, <<"some text">>}

And save it to the database:

{ok, Doc1} = couchbeam:save_doc(Db, Doc).

The couchbeam:save_doc/2 return a new document with updated revision and if you do not specify the _id, a unique document id.

To change an document property use functions from couchbeam_doc.

Retrieve a document

To retrieve a document do:

{ok, Doc2} = couchbeam:open_doc(Db, "test").

If you want a specific revision:

Rev = couchbeamdoc:getrev(Doc1),
Options = [{rev, Rev}],
{ok, Doc3} = couchbeam:open_doc(Db, "test", Options).

Here we get the revision from the document we previously stored. Any options from the Apache CouchDB and RCOUCH API can be used.

Get all documents

To get all documents you have first to create an object that will keep all informations.

Options = [includedocs],
{ok, AllDocs} = couchbeamview:all(Db, Options).

Ex of results:




All functions to manipulate these results are in the couchbeam_view module.

Couch DB views

Views are workin like all_docs. You have to create a View object before doing anything.

Options = [],
DesignName = "designname",
ViewName = "viewname",
{ok, ViewResults} = couchbeam_view:fetch(Db, {DesignName, ViewName}, Options).

Like the all_docs function, use the functions from couchbeam_view module to manipulate results. You can pass any querying options from the view API.

Design doc are created like any documents:

DesignDoc = {[

    {<<"_id">>, <<"_design/couchbeam">>},
                <<"function (doc) {\n if (doc.type == \"test\") {\n emit(doc._id, doc);\n}\n}">>
                <<"function (doc) {\n if (doc.type == \"test2\") {\n emit(doc._id, null);\n}\n}">>

{ok, DesignDoc1} = couchbeam:save_doc(Db, DesignDoc).


You can also use couchapp to manage them more easily.

Stream View results

While you can get results using couchbeam_views:fetch/2, you can also retrieve all rows in a streaming fashion:

ViewFun = fun(Ref, F) ->

    {Ref, done} ->
        io:format("done", []),
    {Ref, {row, Row}} ->
        io:format("got ~p~n", [Row]),
        F(Ref, F);
    {error, Ref, Error} ->
        io:format("error: ~p~n", [Error])


{ok, StreamRef} = couchbeamview:stream(Db, 'alldocs'), ViewFun(StreamRef, ViewFun), {ok, StreamRef2} = couchbeamview:stream(Db, 'alldocs', [include_docs]), ViewFun(StreamRef2, ViewFun).


You can of course do the same with a view:

DesignNam = "designname",
ViewName = "viewname",
{ok, StreamRef3} = couchbeamview:stream(Db, {DesignNam, ViewName}, [includedocs]),
ViewFun(StreamRef3, ViewFun).

Put, Fetch and Delete documents attachments

You can add attachments to any documents. Attachments could be anything.

To send an attachment:

DocID = "test",
AttName = "test.txt",
Att = "some content I want to attach",
Options = []
{ok, Result} = couchbeam:putattachment(Db, DocId, AttName, Att, Options).

All attachments are streamed to servers. Att could be also be an iolist or functions, see couchbeam:put_attachment/5 for more information.

To fetch an attachment:

{ok Att1} = couchbeam:fetch_attachment(Db, DocId, AttName).

You can use couchbeam:streamfetchattachment/6 for the stream fetch.

To delete an attachment:

{ok, Doc4} = couchbeam:opendoc(Db, DocID),
ok = couchbeam:deleteattachment(Db, Doc4, AttName).


Apache CouchDB and RCOUCH provide a means to get a list of changes made to documents in the database. With couchbeam you can get changes using couchbeamchanges:followonce/2. This function returns all changes immediately. But you can also retrieve all changes rows using longpolling :

Options = [],
{ok, LastSeq, Rows} = couchbeamchanges:followonce(Db, Options).

Options can be any Changes query parameters. See the change API for more informations.

You can also get continuous:

ChangesFun = fun(StreamRef, F) ->

    {StreamRef, {done, LastSeq}} ->
        io:format("stopped, last seq is ~p~n", [LastSeq]),
    {StreamRef, {change, Change}} ->
        io:format("change row ~p ~n", [Change]),
        F(StreamRef, F);
    {StreamRef, Error}->
        io:format("error ? ~p ~n,", [Error])

end, Options = [continuous, heartbeat], {ok, StreamRef} = couchbeam_changes:follow(Db, Options), ChangesFun(StreamRef, ChangesFun).


Note: a gen_changes behaviour exists in couchbeam that you can use to create your own specific gen_server receiving changes. Have a look in the example for more info.

Authentication/ Connections options

You can authenticate to the database or Apache CouchDB or RCOUCH server by filling options to the Option list in couchbeam:server_connection/4 for the server or in couchbeam:create_db/3, couchbeam:open_db/3, couchbeam:wopenorcreate_db/3 functions.

To set basic_auth on a server:

UserName = "guest",
Password = "test",
Url = "http://localhost:5984",
Options = [{basicauth, {UserName, Password}}],
S1 = couchbeam:serverconnection(Url, Options).

Couchbeam support SSL, OAuth, Basic Authentication, and Proxy. You can also set a cookie. For more informations about the options have a look in the couchbeam:server_connection/2 documentation.