{"id":16889642,"url":"https://github.com/benoitc/couchbeam","last_synced_at":"2025-05-15T01:04:28.465Z","repository":{"id":621832,"uuid":"261409","full_name":"benoitc/couchbeam","owner":"benoitc","description":"Apache CouchDB client in Erlang","archived":false,"fork":false,"pushed_at":"2025-02-20T22:23:19.000Z","size":2737,"stargazers_count":241,"open_issues_count":13,"forks_count":116,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-06T18:12:38.328Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benoitc.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support/1M","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2009-07-27T07:23:39.000Z","updated_at":"2025-02-20T22:22:27.000Z","dependencies_parsed_at":"2024-02-15T23:32:29.056Z","dependency_job_id":"eadd53da-11b7-4756-8a9d-8c964157f8fc","html_url":"https://github.com/benoitc/couchbeam","commit_stats":{"total_commits":587,"total_committers":56,"mean_commits":"10.482142857142858","dds":"0.24872231686541735","last_synced_commit":"c1facc4c39ace96f31994770618032b75ac7d1a8"},"previous_names":[],"tags_count":57,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benoitc%2Fcouchbeam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benoitc%2Fcouchbeam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benoitc%2Fcouchbeam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benoitc%2Fcouchbeam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benoitc","download_url":"https://codeload.github.com/benoitc/couchbeam/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248785155,"owners_count":21161242,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T16:58:06.917Z","updated_at":"2025-04-13T21:29:29.659Z","avatar_url":"https://github.com/benoitc.png","language":"Erlang","readme":"\n\n# Couchbeam - simple Apache CouchDB client library for Erlang applications #\n\nCopyright (c) 2009-2023 Benoît Chesneau.\n\n__Version:__ 1.5.0\n\n# couchbeam\n\nCouchbeam is a simple erlang library for [Barrel](https://barrel-db.org) or [Apache CouchDB](http://couchdb.apache.org). Couchbeam provides you a full featured and easy client to access and manage multiple nodes.\n\n#### Main features:\n\n- Complete support of the BarrelDB and Apache CouchDB API\n- Stream view results to your app\n- Stream changes feeds\n- reduced memory usage\n- fetch and send attachments in a streaming fashion\n- by default use the JSX module to encode/decode JSON\n- support [Jiffy](http://github.com/davisp/jiffy) a JSON encoder/decoder\nin C.\n\n#### Useful modules are:\n\n- [`couchbeam`](http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam.md): 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...\n- [`couchbeam_doc`](http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_doc.md) Module to manipulate Documents structures. You can set values,\nupdates keys, ...\n- [`couchbeam_attachments`](http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_attachments.md): Module to manipulate attachments. You can add, remove\nattachments in a Document structure (inline attachments).\n- [`couchbeam_view`](http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_view.md): Module to manage view results.\n- [`couchbeam_changes`](http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_changes.md): Module to manage changes feeds. Follow continuously\nthe changes in a db or get all changes at once.\n\nThe goal of Couchbeam is to ease the access to the Apache CouchDB and RCOUCH HTTP API in erlang.\n\nRead the [NEWS](https://raw.github.com/benoitc/couchbeam/master/NEWS) file\nto get last changelog.\n\n## Installation\n\nDownload the sources from our [Github repository](http://github.com/benoitc/couchbeam)\n\nTo build the application simply run 'make'. This should build .beam, .app\nfiles and documentation.\n\nTo run tests run 'make test'.\nTo generate doc, run 'make doc'.\n\nOr add it to your rebar config\n\n```\n   erlang\n{deps, [\n    ....\n    {couchbeam, \".*\", {git, \"git://github.com/benoitc/couchbeam.git\", {branch, \"master\"}}}\n]}.\n```\n\nNote to compile with jiffy you need to define in the erlang options the\nvariable `WITH_JIFFY`.\n\nif you use rebar, add to your `rebar.config`:\n\n```\n   erlang\n{erl_opts, [{d, 'WITH_JIFFY'}]}.\n```\n\nor use the `rebar` command with the `-D` options:\n\n```\n   sh\nrebar compile -DWITH_JIFFY\n```\n\n## Basic Usage\n\n### Start couchbeam\n\nCouchbeam is an [OTP](http://www.erlang.org/doc/design_principles/users_guide.html)\napplication. You have to start it first before using any of the\nfunctions. The couchbeam application will start the default socket pool\nfor you.\n\nTo start in the console run:\n\n```\n   sh\n$ erl -pa ebin\n1\u003e couchbeam:start().\nok\n```\n\nIt will start hackney and all of the application it depends on:\n\n```\n   erlang\napplication:start(crypto),\napplication:start(asn1),\napplication:start(public_key),\napplication:start(ssl),\napplication:start(hackney),\napplication:start(couchbeam).\n```\n\nOr add couchbeam to the applications property of your .app in a release\n\n### Create a connection to the server\n\nTo create a connection to a server machine:\n\n```\n   erlang\nUrl = \"http://localhost:5984\",\nOptions = [],\nS = couchbeam:server_connection(Url, Options).\n```\n\nTest the connection with `couchbeam:server_info/1` :\n\n```\n   erlang\n{ok, _Version} = couchbeam:server_info(S).\n```\n\n### Open or Create a database\n\nAll document operations are done in databases. To open a database simply do:\n\n```\n   erlang\nOptions = [],\n{ok, Db} = couchbeam:open_db(Server, \"testdb\", Options).\n```\n\nTo create a new one:\n\n```\n   erlang\nOptions = [],\n{ok, Db} = couchbeam:create_db(Server, \"testdb\", Options).\n```\n\nYou can also use the shorcut `couchbeam:open_or_create_db/3`. that\nwill create a database if it does not exist.\n\n### Make a new document\n\nMake a new document:\n\n```\n   erlang\nDoc = {[\n{\u003c\u003c\"_id\"\u003e\u003e, \u003c\u003c\"test\"\u003e\u003e},\n{\u003c\u003c\"content\"\u003e\u003e, \u003c\u003c\"some text\"\u003e\u003e}\n]}.\n```\n\nAnd save it to the database:\n\n```\n   erlang\n{ok, Doc1} = couchbeam:save_doc(Db, Doc).\n```\n\nThe `couchbeam:save_doc/2` return a new document with updated\nrevision and if you do not specify the _id, a unique document id.\n\nTo change an document property use functions from `couchbeam_doc`.\n\n### Retrieve a document\n\nTo retrieve a document do:\n\n```\n   erlang\n{ok, Doc2} = couchbeam:open_doc(Db, \"test\").\n```\n\nIf you want a specific revision:\n\n```\n   erlang\nRev = couchbeam_doc:get_rev(Doc1),\nOptions = [{rev, Rev}],\n{ok, Doc3} = couchbeam:open_doc(Db, \"test\", Options).\n```\n\nHere we get the revision from the document we previously stored. Any\noptions from the Apache CouchDB and RCOUCH API can be used.\n\n### Get all documents\n\nTo get all documents you have first to create an object\nthat will keep all informations.\n\n```\n   erlang\nOptions = [include_docs],\n{ok, AllDocs} = couchbeam_view:all(Db, Options).\n```\n\nEx of results:\n\n```\n   erlang\n{ok,[{[{\u003c\u003c\"id\"\u003e\u003e,\u003c\u003c\"7a0ce91d0d0c5e5b51e904d1ee3266a3\"\u003e\u003e},\n          {\u003c\u003c\"key\"\u003e\u003e,\u003c\u003c\"7a0ce91d0d0c5e5b51e904d1ee3266a3\"\u003e\u003e},\n          {\u003c\u003c\"value\"\u003e\u003e,\n           {[{\u003c\u003c\"rev\"\u003e\u003e,\u003c\u003c\"15-15c0b3c4efa74f9a80d28ac040f18bdb\"\u003e\u003e}]}},\n          {\u003c\u003c\"doc\"\u003e\u003e,\n           {[{\u003c\u003c\"_id\"\u003e\u003e,\u003c\u003c\"7a0ce91d0d0c5e5b51e904d1ee3266a3\"\u003e\u003e},\n             {\u003c\u003c\"_rev\"\u003e\u003e,\u003c\u003c\"15-15c0b3c4efa74f9a80d28ac040f18\"...\u003e\u003e}]}}]},\n        ]}.\n```\n\nAll functions to manipulate these results are in the `couchbeam_view` module.\n\n### Couch DB views\n\nViews are workin like all_docs. You have to create a View object before\ndoing anything.\n\n```\n   erlang\nOptions = [],\nDesignName = \"designname\",\nViewName = \"viewname\",\n{ok, ViewResults} = couchbeam_view:fetch(Db, {DesignName, ViewName}, Options).\n```\n\nLike the `all_docs` function, use the functions\nfrom `couchbeam_view` module to manipulate results. You can pass\nany querying options from the [view API](http://docs.rcouch.org/en/latest/api/ddoc/views.html).\n\nDesign doc are created like any documents:\n\n```\n   erlang\nDesignDoc = {[\n        {\u003c\u003c\"_id\"\u003e\u003e, \u003c\u003c\"_design/couchbeam\"\u003e\u003e},\n        {\u003c\u003c\"language\"\u003e\u003e,\u003c\u003c\"javascript\"\u003e\u003e},\n        {\u003c\u003c\"views\"\u003e\u003e,\n            {[{\u003c\u003c\"test\"\u003e\u003e,\n                {[{\u003c\u003c\"map\"\u003e\u003e,\n                    \u003c\u003c\"function (doc) {\\n if (doc.type == \\\"test\\\") {\\n emit(doc._id, doc);\\n}\\n}\"\u003e\u003e\n                }]}\n            },{\u003c\u003c\"test2\"\u003e\u003e,\n                {[{\u003c\u003c\"map\"\u003e\u003e,\n                    \u003c\u003c\"function (doc) {\\n if (doc.type == \\\"test2\\\") {\\n emit(doc._id, null);\\n}\\n}\"\u003e\u003e\n                }]}\n            }]}\n        }\n    ]},\n{ok, DesignDoc1} = couchbeam:save_doc(Db, DesignDoc).\n```\n\nYou can also use [couchapp](http://github.com/couchapp/couchapp) to manage them\nmore easily.\n\n### Stream View results\n\nWhile you can get results using `couchbeam_views:fetch/2`, you can also retrieve\nall rows in a streaming fashion:\n\n```\n   erlang\nViewFun = fun(Ref, F) -\u003e\n    receive\n        {Ref, done} -\u003e\n            io:format(\"done\", []),\n            done;\n        {Ref, {row, Row}} -\u003e\n            io:format(\"got ~p~n\", [Row]),\n            F(Ref, F);\n        {error, Ref, Error} -\u003e\n            io:format(\"error: ~p~n\", [Error])\n    end\nend,\n\n{ok, StreamRef} = couchbeam_view:stream(Db, 'all_docs'),\nViewFun(StreamRef, ViewFun),\n{ok, StreamRef2} = couchbeam_view:stream(Db, 'all_docs', [include_docs]),\nViewFun(StreamRef2, ViewFun).\n```\n\nYou can of course do the same with a view:\n\n```\n   erlang\nDesignNam = \"designname\",\nViewName = \"viewname\",\n{ok, StreamRef3} = couchbeam_view:stream(Db, {DesignNam, ViewName}, [include_docs]),\nViewFun(StreamRef3, ViewFun).\n```\n\n### Put, Fetch and Delete documents attachments\n\nYou can add attachments to any documents. Attachments could be anything.\n\nTo send an attachment:\n\n```\n   erlang\nDocID = \"test\",\nAttName = \"test.txt\",\nAtt = \"some content I want to attach\",\nOptions = []\n{ok, _Result} = couchbeam:put_attachment(Db, DocId, AttName, Att, Options).\n```\n\nAll attachments are streamed to servers. `Att` could be also be an iolist\nor functions, see `couchbeam:put_attachment/5` for more information.\n\nTo fetch an attachment:\n\n```\n   erlang\n{ok Att1} = couchbeam:fetch_attachment(Db, DocId, AttName).\n```\n\nYou can use `couchbeam:stream_fetch_attachment/6` for the stream\nfetch.\n\nTo delete an attachment:\n\n```\n   erlang\n{ok, Doc4} = couchbeam:open_doc(Db, DocID),\nok = couchbeam:delete_attachment(Db, Doc4, AttName).\n```\n\n### Changes\n\nApache CouchDB and RCOUCH provide a means to get a list of changes made to documents in\nthe database. With couchbeam you can get changes using `couchbeam_changes:follow_once/2`.\nThis function returns all changes immediately. But you can also retrieve\nall changes rows using longpolling :\n\n```\n   erlang\nOptions = [],\n{ok, LastSeq, Rows} = couchbeam_changes:follow_once(Db, Options).\n```\n\nOptions can be any Changes query parameters. See the [change API](http://docs.rcouch.org/en/latest/api/database/changes.html) for more informations.\n\nYou can also get [continuous](http://docs.rcouch.org/en/latest/api/database/changes.html#continuous):\n\n```\n   erlang\nChangesFun = fun(StreamRef, F) -\u003e\n    receive\n        {StreamRef, {done, LastSeq}} -\u003e\n            io:format(\"stopped, last seq is ~p~n\", [LastSeq]),\n            ok;\n        {StreamRef, {change, Change}} -\u003e\n            io:format(\"change row ~p ~n\", [Change]),\n            F(StreamRef, F);\n        {StreamRef, Error}-\u003e\n            io:format(\"error ? ~p ~n,\", [Error])\n    end\nend,\nOptions = [continuous, heartbeat],\n{ok, StreamRef} = couchbeam_changes:follow(Db, Options),\nChangesFun(StreamRef, ChangesFun).\n```\n\n\u003e **Note**: a `gen_changes` behaviour exists in couchbeam that you can\nuse to create your own specific gen_server receiving changes. Have a\nlook in the\n[example](https://github.com/benoitc/couchbeam/blob/master/examples/test_gen_changes.erl)\nfor more info.\n\n### Authentication/ Connections options\n\nYou can authenticate to the database or Apache CouchDB or RCOUCH server by filling\noptions to the Option list in `couchbeam:server_connection/4` for the\nserver or in `couchbeam:create_db/3`, `couchbeam:open_db/3`,\n`couchbeam:wopen_or_create_db/3` functions.\n\nTo set basic_auth on a server:\n\n```\n   erlang\nUserName = \"guest\",\nPassword = \"test\",\nUrl = \"http://localhost:5984\",\nOptions = [{basic_auth, {UserName, Password}}],\nS1 = couchbeam:server_connection(Url, Options).\n```\n\nCouchbeam support SSL, OAuth, Basic Authentication, and Proxy. You can\nalso set a cookie. For more informations about the options have a look\nin the `couchbeam:server_connection/2` documentation.\n\n## Contribute\n\nFor issues, comments or feedback please [create an\nissue](http://github.com/benoitc/couchbeam/issues).\n\n\n## Modules ##\n\n\n\u003ctable width=\"100%\" border=\"0\" summary=\"list of modules\"\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam.md\" class=\"module\"\u003ecouchbeam\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_app.md\" class=\"module\"\u003ecouchbeam_app\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_attachments.md\" class=\"module\"\u003ecouchbeam_attachments\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_changes.md\" class=\"module\"\u003ecouchbeam_changes\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_changes_stream.md\" class=\"module\"\u003ecouchbeam_changes_stream\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_changes_sup.md\" class=\"module\"\u003ecouchbeam_changes_sup\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_doc.md\" class=\"module\"\u003ecouchbeam_doc\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_ejson.md\" class=\"module\"\u003ecouchbeam_ejson\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_httpc.md\" class=\"module\"\u003ecouchbeam_httpc\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_sup.md\" class=\"module\"\u003ecouchbeam_sup\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_util.md\" class=\"module\"\u003ecouchbeam_util\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_uuids.md\" class=\"module\"\u003ecouchbeam_uuids\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_view.md\" class=\"module\"\u003ecouchbeam_view\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_view_stream.md\" class=\"module\"\u003ecouchbeam_view_stream\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/couchbeam_view_sup.md\" class=\"module\"\u003ecouchbeam_view_sup\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ca href=\"http://github.com/benoitc/couchbeam/blob/master/doc/gen_changes.md\" class=\"module\"\u003egen_changes\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenoitc%2Fcouchbeam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenoitc%2Fcouchbeam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenoitc%2Fcouchbeam/lists"}