couchex v0.8.0 Couchex

Wrapper around the couchbeam erlang couchdb client

Summary

Functions

Returns all documents in a database

Returns a list of all databases

Compacts a database

Compacts the view index

Creates a database. The database must NOT exist

  • CouchDB 2.0 only - Creates an index

Checks if database exist

Returns database info

Delete attachment from document

Deletes a database. The database must exist

Deletes a database. The database must exist

Delete a document

Deletes a list of documents

Returns true if document exists

Fetch attachment from document

  • CouchDB 2.0 only - Retreives all documents via mango query

Follow database changes

Returns current document revision

Retreives document as map, by id with or without revision

Put an attachment to document

Replicates a database from source to target

Save and update a document

Returns a server connection

Returns basic info about server

Returns a single server generated uuid

Returns a total of number server generated uuids

Functions

all(db, options \\ [:include_docs])

Returns all documents in a database

Examples

Couchex.all(db)
#=> [
      %{
        "doc" => %{"_id" => "doc_id_1", "_rev" => "...", "foo" => "bar"},
        "id" => "doc_id_1",
        "key" => "doc_id_1",
        "value" => %{"rev" => "..."}
      },
      %{"doc" => %{"_id" => "doc_id_2", ...
    ]
all_dbs(server)

Returns a list of all databases

Examples

Couchex.all_dbs(server)
#=> {:ok, ["_replicator", "_users", "some_db", ...]}
compact(db)

Compacts a database.

Wiki

Examples

{:ok, db} = Couchex.open_db(server, "couchex")
Couchex.compact(db)
#=> :ok
compact(db, design_name)

Compacts the view index.

Wiki

Examples

{:ok, db} = Couchex.open_db(server, "couchex")
Couchex.compact(db, "design_name")
#=> :ok
create_db(server, db_name, options \\ [])

Creates a database. The database must NOT exist

Examples

Couchex.create_db(server, "couchex")
#=> {:db, server, "couchex", [basic_auth: {"username", "password"}]}}
Couchex.create_db(server, "couchex")
#=> {:error, :db_exists}
create_index(db, index)
  • CouchDB 2.0 only - Creates an index

Examples

index = %{ "name" => "name-index", "type" => "json", "index" => %{ "fields" => [ %{ "key": "asc" } ] } }
Couchex.create_index(db, index)
#=> {:ok, %{id: "id", name: "name-index", status: :created}}
db_exists?(server, db_name)

Checks if database exist.

Examples

Couchex.db_exists?(server, "couchex")
#=> true
db_info(db)

Returns database info.

Examples

{:ok, db} = Couchex.open_db(server, "couchex")
Couchex.db_info(db)
#=> %{"committed_update_seq" => 0, "compact_running" => false, "data_size" => 227,
    "db_name" => "couchex", "disk_format_version" => 6, "disk_size" => 306,
    "doc_count" => 1, "doc_del_count" => 0,
    "instance_start_time" => "1423503379138489", "purge_seq" => 0,
    "update_seq" => 1}
delete_attachment(db, map, attachment_name)

Delete attachment from document

This method is idempotent, and will increment the document revision, even though the attachment isn’t present(e.g. already deleted)

Examples

attachment_name = "file.txt"

Couchex.delete_attachment(db, %{id: "18c359e463c37525e0ff484dcc0003b7"}, attachment_name)
#=> {:ok, %{"id" => "18c359e463c37525e0ff484dcc0003b7", "rev" => "4-ebe18f0e4f4c3c717a9e9291bc2465b3"}}

Couchex.delete_attachment(db, %{id: "18c359e463c37525e0ff484dcc0003b7", rev: "3-ebe18f0e4f4c3c717a9e9291bc2465b3"}, attachment_name)
#=> {:ok, %{"id" => "18c359e463c37525e0ff484dcc0003b7", "rev" => "4-ebe18f0e4f4c3c717a9e9291bc2465b3"}}
delete_db(db)

Deletes a database. The database must exist

Examples

{:ok, db} = Couchex.open_db(server, "couchex")
#=> {:ok, {:db, server, "couchex", []}}
Couchex.delete_db(db)
#=> {:ok, :db_deleted}
Couchex.delete_db(db)
#=> {:error, :not_found}
delete_db(server, db_name)

Deletes a database. The database must exist

Examples

Couchex.delete_db(server, "couchex")
#=> {:ok, :db_deleted}
Couchex.delete_db(server, "couchex")
#=> {:error, :not_found}
delete_doc(db, map)

Delete a document

Examples

Couchex.delete_doc(db, %{id: "18c359e463c37525e0ff484dcc0003b7", rev: "1-59414e77c768bc202142ac82c2f129de"})
#=> %{"id" => "18c359e463c37525e0ff484dcc0003b7", "ok" => true, "rev" => "2-9b2e3bcc3752a3a952a3570b2ed4d27e"}
delete_docs(db, list)

Deletes a list of documents

Examples

Couchex.delete_docs(db, [%{id: "18c359e463c37525e0ff484dcc0003b7", rev: "1-59414e77c768bc202142ac82c2f129de"}])
#=> [%{"id" => "18c359e463c37525e0ff484dcc0003b7", "ok" => true, "rev" => "2-9b2e3bcc3752a3a952a3570b2ed4d27e"}]
doc_exists?(db, doc_id)

Returns true if document exists

Examples

Couchex.doc_exists?(db, "EXISTING_DOC_ID")
#=> true

Couchex.doc_exists?(db, "NONE_EXISTING_DOC_ID")
#=> false
fetch_attachment(db, doc_id, attachment_name)

Fetch attachment from document

Examples

doc_id = "18c359e463c37525e0ff484dcc0003b7"
attachment_name = "file.txt"
Couchex.fetch_attachment(db, doc_id, attachment_name)
#=> {:ok, "SOME DATA - HERE IT'S TEXT"}
fetch_view(db, arg, options \\ [])

Fetch view

Examples

{:ok, res} = Couchex.fetch_view(db, {"lists","company_users_by_income"},[:group])

When having a design doc like this,

design_doc = %{
   "_id" => "_design/lists",
   "language": "javascript",
   "views": %{
       "by_customer_id": %{
           "map": "function(doc) {  emit(doc.customer_id, doc);}"
       }
   }
}

fetch docs by customer id

{:ok, res} = Couchex.fetch_view(db, {"lists","by_customer_id"},[key: customer_id])
find(db, query)
  • CouchDB 2.0 only - Retreives all documents via mango query

Examples

query = %{
  "selector": %{
    "_id": %{
      "$gt": nil
    }
  }
}
Couchex.find(db, query)
#=> %{ docs: [%{"_id" => "..."}, ...], warning: <ONLY IF WARNING SENT FROM SERVER> }
follow(db, options \\ [])

Follow database changes

Examples

def changes_fun(stream_ref) do
  receive do
    {stream_ref, {:done, last_seq}} ->
      Logger.info "Stopped at seq: #{inspect last_seq}"
      :ok
    {stream_ref, {:change, change}} ->
      Logger.info "Change: #{inspect change}"
      changes_fun(stream_ref)
    {stream_ref, error}->
      Log.error "#{inspect error}"
    msg ->
      Logger.warn "#{inspect msg}"
  end
end

Couchex.follow(db, [:continuous, :heartbeat])
#=> {:ok, <stream_ref>}
changes_fun(<stream_ref>)
follow_once(db, options \\ [])
lookup_doc_rev(db, id)

Returns current document revision

Examples

Couchex.lookup_doc_rev(db, "18c359e463c37525e0ff484dcc0003b7")
#=> {:ok, "1-59414e77c768bc202142ac82c2f129de"}
open_db(server, db_name, options \\ [])

Opens a database

If credentials were passed during server_connection, they will be passed on to open_db. They will however be overwritten by the credentials applied to open_db

Examples

Couchex.open_db(server, "couchex")
#=> {:ok, {:db, server, "couchex", []}}

Couchex.open_db(server, "couchex", [{:basic_auth, {"username", "password"}}])
#=> {:ok, {:db, server, "couchex", [{:basic_auth, {"username", "password"}}]}}
open_doc(db, map)

Retreives document as map, by id with or without revision

Examples

Couchex.open_doc(db, %{id: id})
#=> {:ok, %{"_id" => id, "_rev" => rev, ...}}

Couchex.open_doc(db, %{id: id, rev: revision})
#=> {:ok, %{"_id" => id, "_rev" => rev, ...}}
put_attachment(db, map, attachment)

Put an attachment to document

Examples

attachment = %{ name: "image.png", data: "....", content_type: "image/png" }
Couchex.put_attachment(db, %{id: id}, attachment) # latest revision
#=> {:ok, %{"id" => "18c359e463c37525e0ff484dcc0003b7", "rev" => "3-ebe18f0e4f4c3c717a9e9291bc2465b3"}}

doc_id = "18c359e463c37525e0ff484dcc0003b7"
revision = "1-59414e77c768bc202142ac82c2f129de"
content_type = Couchex.MIME.type("txt") # => "text/plain"
attachment = %{ name: "file.txt", data: "SOME DATA - HERE IT'S TEXT", content_type: content_type }
Couchex.put_attachment(db, %{id: doc_id, rev: revision}, attachment)
#=> {:ok, %{"id" => "18c359e463c37525e0ff484dcc0003b7", "rev" => "3-ebe18f0e4f4c3c717a9e9291bc2465b3"}}
replicate(server, rep_obj)

Replicates a database from source to target

Examples

create_target param, target db is created if not already present

continuous param, replication runs continuously until server restart

Couchex.replicate(server, %{source: "sourcedb", target: "targetdb", create_target: true})
#=> {:ok, %{"history" => [...], "ok" => true, "replication_id_version" => 3, "session_id" => "b3457b342b2eb31ea0f85e77bac03a66", "source_last_seq" => 16}}

Couchex.replicate(server, %{source: "https://user:pass@sourcedb", target: "targetdb", create_target: true})
#=> {:ok, resp}

Couchex.replicate(server, %{source: "https://user:pass@sourcedb", target: "http://user:pass@targetdb", create_target: true})
#=> {:ok, resp}

Couchex.replicate(server, %{source: "https://user:pass@sourcedb", target: "http://user:pass@targetdb", create_target: true, continuous: true})
#=> #=> {:ok, %{"Cache-Control" => "must-revalidate", "Content-Length" => "84", "Content-Type" => "application/json", "Date" => "Mon, 09 Feb 2015 16:24:19 GMT", "Server" => "CouchDB/1.5.0 (Erlang OTP/R16B03)"}}
save_doc(db, doc)

Save and update a document

Update a document, by using an existing document id

Please remark the use of %{"_id" => "ID", ...} and not %{"_id": "ID", ...}, the latter will not work

Examples

Couchex.save_doc(db, %{"key" => "value"}) # Couch auto creates id
#=> %{"_id" => "c1cdba4b7d7a963b9ca7c5445684679f", "_rev" => "1-59414e77c768bc202142ac82c2f129de", "key" => "value"}

Couchex.save_doc(db, %{"_id" => "FIRST_ID", "key" => "value"}) # User defined id
#=> %{"_id" => "FIRST_ID", "_rev" => "1-59414e77c768bc202142ac82c2f129de", "key" => "value"}
server_connection()

Returns a server connection

Examples

Couchex.server_connection("url")
#=> {:server, "url", []}

Couchex.server_connection(@couchdb_url, [{:basic_auth, {"username", "password"}}])
#=> {:server, "url", [{:basic_auth, {"username", "password"}}]}
server_connection(url, options \\ [])
server_info(server)

Returns basic info about server

Examples

Couchex.server_info(server)
#=> %{"couchdb" => "Welcome", "uuid" => "c1cdba4b7d7a963b9ca7c5445684679f", "vendor" => {[{"version", "1.5.0-1"}, {"name", "Homebrew"}]}, "version" => "1.5.0"}
uuid(server)

Returns a single server generated uuid

Examples

Couchex.uuid(server)
#=> "267732468d85b6fd22504aeaa4dc68e3"
uuids(server, number)

Returns a total of number server generated uuids

Examples

Couchex.uuids(server, 3)
#=> ["267732468d85b6fd22504aeaa4fb8ac9", "267732468d85b6fd22504aeaa4fb8065", "267732468d85b6fd22504aeaa4fb7ca7"]