• Stars
    star
    238
  • Rank 169,306 (Top 4 %)
  • Language
    Erlang
  • License
    Other
  • Created over 15 years ago
  • Updated almost 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Apache CouchDB client in Erlang

Couchbeam - simple Apache CouchDB client library for Erlang applications

Copyright (c) 2009-2023 Benoît Chesneau.

Version: 1.5.0

couchbeam

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:

  • Complete support of the BarrelDB and Apache CouchDB API
  • Stream view results to your app
  • Stream changes feeds
  • reduced memory usage
  • fetch and send attachments in a streaming fashion
  • by default use the JSX module to encode/decode JSON
  • support Jiffy a JSON encoder/decoder in C.

Useful modules are:

  • couchbeam: The couchbeam module is the main interface for interaction with this application. It includes functions for managing connections to Apache CouchDB or RCOUCH servers and databases and for performing document creations, updates, deletes, views...
  • couchbeam_doc Module to manipulate Documents structures. You can set values, updates keys, ...
  • couchbeam_attachments: Module to manipulate attachments. You can add, remove attachments in a Document structure (inline attachments).
  • couchbeam_view: Module to manage view results.
  • couchbeam_changes: Module to manage changes feeds. Follow continuously the changes in a db or get all changes at once.

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.

Installation

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

   erlang
{deps, [
    ....
    {couchbeam, ".*", {git, "git://github.com/benoitc/couchbeam.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:

   erlang
{erl_opts, [{d, 'WITH_JIFFY'}]}.

or use the rebar command with the -D options:

   sh
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:

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

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

   erlang
application:start(crypto),
application:start(asn1),
application:start(public_key),
application:start(ssl),
application:start(hackney),
application:start(couchbeam).

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:

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

Test the connection with couchbeam:server_info/1 :

   erlang
{ok, _Version} = couchbeam:server_info(S).

Open or Create a database

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

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

To create a new one:

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

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

Make a new document

Make a new document:

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

And save it to the database:

   erlang
{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:

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

If you want a specific revision:

   erlang
Rev = couchbeam_doc:get_rev(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.

   erlang
Options = [include_docs],
{ok, AllDocs} = couchbeam_view:all(Db, Options).

Ex of results:

   erlang
{ok,[{[{<<"id">>,<<"7a0ce91d0d0c5e5b51e904d1ee3266a3">>},
          {<<"key">>,<<"7a0ce91d0d0c5e5b51e904d1ee3266a3">>},
          {<<"value">>,
           {[{<<"rev">>,<<"15-15c0b3c4efa74f9a80d28ac040f18bdb">>}]}},
          {<<"doc">>,
           {[{<<"_id">>,<<"7a0ce91d0d0c5e5b51e904d1ee3266a3">>},
             {<<"_rev">>,<<"15-15c0b3c4efa74f9a80d28ac040f18"...>>}]}}]},
        ]}.

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.

   erlang
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:

   erlang
DesignDoc = {[
        {<<"_id">>, <<"_design/couchbeam">>},
        {<<"language">>,<<"javascript">>},
        {<<"views">>,
            {[{<<"test">>,
                {[{<<"map">>,
                    <<"function (doc) {\n if (doc.type == \"test\") {\n emit(doc._id, doc);\n}\n}">>
                }]}
            },{<<"test2">>,
                {[{<<"map">>,
                    <<"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:

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

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

You can of course do the same with a view:

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

Put, Fetch and Delete documents attachments

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

To send an attachment:

   erlang
DocID = "test",
AttName = "test.txt",
Att = "some content I want to attach",
Options = []
{ok, _Result} = couchbeam:put_attachment(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:

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

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

To delete an attachment:

   erlang
{ok, Doc4} = couchbeam:open_doc(Db, DocID),
ok = couchbeam:delete_attachment(Db, Doc4, AttName).

Changes

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 couchbeam_changes:follow_once/2. This function returns all changes immediately. But you can also retrieve all changes rows using longpolling :

   erlang
Options = [],
{ok, LastSeq, Rows} = couchbeam_changes:follow_once(Db, Options).

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

You can also get continuous:

   erlang
ChangesFun = fun(StreamRef, F) ->
    receive
        {StreamRef, {done, LastSeq}} ->
            io:format("stopped, last seq is ~p~n", [LastSeq]),
            ok;
        {StreamRef, {change, Change}} ->
            io:format("change row ~p ~n", [Change]),
            F(StreamRef, F);
        {StreamRef, Error}->
            io:format("error ? ~p ~n,", [Error])
    end
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:wopen_or_create_db/3 functions.

To set basic_auth on a server:

   erlang
UserName = "guest",
Password = "test",
Url = "http://localhost:5984",
Options = [{basic_auth, {UserName, Password}}],
S1 = couchbeam:server_connection(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.

Contribute

For issues, comments or feedback please create an issue.

Modules

couchbeam
couchbeam_app
couchbeam_attachments
couchbeam_changes
couchbeam_changes_stream
couchbeam_changes_sup
couchbeam_doc
couchbeam_ejson
couchbeam_httpc
couchbeam_sup
couchbeam_util
couchbeam_uuids
couchbeam_view
couchbeam_view_stream
couchbeam_view_sup
gen_changes

More Repositories

1

gunicorn

gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX, fast clients and sleepy applications.
Python
9,757
star
2

hackney

simple HTTP client in Erlang
Erlang
1,322
star
3

restkit

an HTTP resource kit for Python
Python
405
star
4

offset

Python
377
star
5

gaffer

control, watch and launch your applications and jobs over HTTP.
Python
363
star
6

http-parser

HTTP request/response parser for python in C
C
337
star
7

erica

tool to manage couchapps
JavaScript
269
star
8

tproxy

simple TCP routing proxy
Python
265
star
9

couchdbkit

CouchDB python framework
Python
265
star
10

flower

collection of modules to build distributed and reliable concurrent systems in Python.
Python
207
star
11

socketpool

Generic socket pool
Python
163
star
12

cowboy_revproxy

simple TCP routing proxy (layer 7) in erlang
Erlang
86
star
13

econfig

simple Erlang config handler using INI files
Erlang
79
star
14

hooks

generic plugin & hook system for Erlang applications
Erlang
72
star
15

erlang-metrics

A generic interface to different metrics systems in Erlang.
Erlang
70
star
16

dj-webmachine

Django REST layer
Python
59
star
17

erlang-nat

implements NAT handling facilities for Erlang applications
Erlang
57
star
18

couchdbproxy

Simple multinode couchdb proxy
Erlang
57
star
19

dnssd_erlang

Erlang interface to Apple's Bonjour DNS Service Discovery implementation
Erlang
46
star
20

nat_upnp

Erlang library to map your internal port to an external using UNP IGD
Erlang
42
star
21

uzmq

libuv interface for ZeroMQ
Python
34
star
22

ejson

EJSON - decode and encode JSON into/from Erlang terms (from CouchDB project)
C
32
star
23

mochicow

mochiweb adapter for cowboy.
Erlang
29
star
24

dj-revproxy

simple reverse proxy for django.
Python
28
star
25

hroute

simple HTTP proxy based on tproxy
Python
28
star
26

inet_cidr

CIDR erlang library
Erlang
27
star
27

mimerl

library to handle mimetypes
Erlang
27
star
28

sieve

sieve is a simple TCP routing proxy (layer 7) in erlang
Erlang
26
star
29

opencouch

A embeddable document oriented database compatible with Apache CouchDB
Erlang
22
star
30

gunicorn-recipes

Collection of recipe and examples to help in gunicorn deployement, installation and configuration.
19
star
31

nymphormation

Nymphormation is a Couchapp that allow people to share links or news .
JavaScript
19
star
32

rebar3_path_deps

A rebar plugin to specify path dependencies.
Erlang
19
star
33

couch_zmq

zeromq endpoint for couchdb.
Erlang
18
star
34

noddycouch

minimal couchdb toolkit for nodejs.
JavaScript
17
star
35

afgwardiary

couchapp to render afgwardiary data from wikileaks
JavaScript
16
star
36

upnp

Erlang UPNP Module
Erlang
14
star
37

couchc

minimal couchdb internal API wrapper
Erlang
14
star
38

couchapp-ng

Couchapp Engine
Erlang
14
star
39

couchdb

My CouchDB hack repository
JavaScript
14
star
40

cbt

multi-layer MVCC log append-only database library based on the Apache CouchDB btree.
Erlang
14
star
41

inet_ext

inet extensions library
Erlang
13
star
42

hackney_lib

WEB toolkit including miscellaneous modules to play with HTTP and Web protocols
Erlang
11
star
43

memdb

Erlang memory backend K/V store
Erlang
10
star
44

rebar3_protobuffs

rebar3 protobuffs provider using protobuffs from Basho
Erlang
10
star
45

unicode_util_compat

unicode_util compatibility library for Erlang < 20
Erlang
10
star
46

fserve

simple file server in python on unix systems with sendfile support using pistil
Python
8
star
47

pywebmachine

Python port of Basho's WebMachine
Python
8
star
48

hypercouch

Full text indexing of CouchDB via HyperEstraier
Python
7
star
49

natpmp

Erlang Nat-PMP client
Erlang
7
star
50

rcouch_template

Rebar templates for generating custom couchdb releases
Shell
7
star
51

dotfiles

repository of dotifile in my home
Vim Script
6
star
52

hackney_disp

Load-balanced Pool dispatcher based on dispcount for hackney.
Erlang
6
star
53

benoitc.org

My own site
JavaScript
6
star
54

couchdb_internals

Miscelleaneous docs about the couchdb protocol and couchdb implementation
6
star
55

dcouch

an Alternative to Mnesia with Unique Features
5
star
56

backbone.py

just some code to initiate construction of objects from any remote repo.
Python
5
star
57

nplib

library collecting modules to decode a bunch of network protocoles
Erlang
5
star
58

qrkit

simple and stupid qr code binding extracted from qrurl
Python
5
star
59

couchdocs

Documentation for CouchDB
Objective-C
5
star
60

lhttpc-old

GIT clone of http://bitbucket.org/etc/lhttpc/
Erlang
4
star
61

blanket

couchdb/refuge client.
4
star
62

couch_randomdoc

simple couchdb module to add support of random document fetching.
Erlang
4
star
63

erlang-pbkdf2-nif

PBKDF2 NIF implementation
C
4
star
64

couchdb-old

Couchdb mirror repo to handle some custom dev
Erlang
4
star
65

rebar3_cargo

Erlang
4
star
66

erl_stun

Erlang
4
star
67

hackney_pooler

Experiment an API to limit the number of hackney requests launched concurrently
Erlang
4
star
68

emonk_helper

Some extensiosn to ease the use of emonk (http://github.com/davisp/emonk)
Erlang
3
star
69

couchjs

rebar couchjs version for CouchDB
JavaScript
3
star
70

dj-cookieauth

Secure Cookie Auth module for Django
Python
3
star
71

cablesgate

Script to put wikileaks diploamatic cables in a couchdb
Python
3
star
72

echohttp

simple service echoing any requests made to http://echohttp.com/echo
Erlang
3
star
73

mt-compono

minimalist cms using Django
JavaScript
3
star
74

dj-pages

minimal content cms/renderer
JavaScript
3
star
75

build-android

Shell
3
star
76

vrac

Simple app to manage all data fragments in vurt
JavaScript
3
star
77

erlang-idna-nif

C
3
star
78

esync

simple tool to sync files
Erlang
3
star
79

epygments

Simple wrapper to Pygments - prettify source code in your erlang program.
Erlang
3
star
80

libcouch

Pure Erlang CouchDB Store library.
Erlang
3
star
81

overlay

CSS
3
star
82

buildout_couchdb

zc buildout recipe for Apache CouchDB server
Python
3
star
83

dummy_app

Erlang
2
star
84

hello_world

Erlang
2
star
85

wineoverip

JavaScript
2
star
86

foodoverip

Handle #foodoverip
JavaScript
2
star
87

couchit_experiment

Standalone couch.it powered by CouchDB
Erlang
2
star
88

benoitc.github.com

Github Homepage
2
star
89

dataporn

intensive data usage
2
star
90

qrurl

C
2
star
91

enki

Document-oriented database framework
2
star
92

mod_percept2

percept2 ejabberd module
JavaScript
1
star
93

tiptoe

1
star
94

mz_counter

simple atomic counter for erlang applications
C
1
star
95

enki--multimedia.org

1
star
96

unicode_extra

Extra function not available in Erlang unicode_util module
Erlang
1
star
97

erlang-ucs

1
star
98

osdc2013_demo

demo for OSDC 2013
Erlang
1
star