couchdb_ex v0.1.1 CouchDBEx

Main entrypoint to the CouchDBEx API.

Authentification

This module supports both basic and cookie authentification with automatic cookie renewal.

To use authentification, you’ll need to pass the username and password parameters at the module start and set auth_method to either :cookie or :basic, you also can just not provide any of those, then there will not be any authentification going on.

Basic authentifcation will pass the Authrorization header with every request you make, this header will contain base64 encoded login and password, be aware that is is insecure.

The other method is more secure: when the worker starts, it will initiate a session with the database and use the cookie it provides until the :cookie_session_minutes timout (9 minutes by default, since CouchDB sessions time out in 10 minutes with the default database configuration). When the cookie times out, it will be renewed automatically by the internal auth agent; you probably want to set this option one minute less than the actual database configuration just to be safe.

You can read more about authentification here

Examples

Example module specification for the supervisor:

children = [
    {CouchDBEx.Worker, [
        hostname: "http://localhost",
        username: "couchdb",
        password: "couchdb",
        auth_method: :cookie,
        cookie_session_minutes: 9
      ]}
  ]

opts = [strategy: :one_for_one, name: CouchDBEx.Test.Supervisor]
Supervisor.start_link(children, opts)

Link to this section Summary

Functions

Subscribe to changes to the table

Unsubscribe the modname watcher from changes in the database

Set the configuration option for the CouchDB server

Set a configuration option for the CouchDB server

Queries the CouchDB server for some general information about it (e.g. version)

Request compaction of the specified database

Create a new database

Deletes the specified database, and all the documents and attachments contained within it

Checks if the specified database exists

Get some general information about the database, this includes it’s name, size and clustering information

Get the list of all databases, this list includes system databases like _users

Delete multiple documents from the database, id_rev is an array of documents’ {id, revision}

Delete a single document from the database

Find a document in the database using the selector spec

Get a document from the database

Insert or update multiple documents, for a single document see CouchDBEx.document_insert_one/2

Insert or update a single document, for multiple documents see CouchDBEx.document_insert_many/2

Lists all (or filtered) documents in the database, along with their number

Delete the index index_name from the specified design document ddoc

Lists all indexes and their count

Replicate a database

Get a single UUID from the server

Get several UUIDs from the server

Link to this section Types

Link to this type couchdb_res()
couchdb_res() :: {:ok, map()} | {:error, term()}

Link to this section Functions

Link to this function attachment_upload(db, id, name, bindata, doc_rev, opts \\ [])
attachment_upload(
  db :: String.t(),
  id :: String.t(),
  name :: String.t(),
  bindata :: binary(),
  doc_rev :: String.t(),
  opts :: keyword()
) :: {:ok, [id: String.t(), rev: String.t()]} | {:error, term()}

Upload an attachment to the document.

id is the document id to which the attachment will be added, name is the attacument’s name, bindata is binary data which will be uploaded (essentialy, anything that satisfies the is_binary/1 constraint), doc_rev is current document revision.

Options

  • content_type - content type of the attachment in the standard format (e.g. text/plain), this option will set the Content-Type header for the request.
Link to this function changes_sub(db, modname, watcher_name, opts \\ [])

Subscribe to changes to the table.

watcher_name is the process name the caller wants the watcher to be known as, the watcher may set this name on start (it will be passed as :name in the options list) so that other processes could communicate with it, otherwise it is used only as a Supervisor id. This facilitates module reuse, as one might want to use same modules on different databases. modname is the actual module that will be passed to the supervisor, which in turn will start it.

The watching module

The module passed to this function will periodically receive update messages from the database in the tuple with :couchdb_change as it’s first element and the change as the second element. If the module crashes, it will be restarted by a supervisor. To stop the watcher and remove it, see CouchDBEx.changes_unsub/1

Module example

defmodule ChangesTest do
  use GenServer

  def start_link(opts) do
    GenServer.start_link(__MODULE__, nil, opts)
  end

  def init(_) do
    {:ok, nil}
  end

  def handle_info({:couchdb_change, msg}, _) do
    # Just logs the change to the stdout
    IO.inspect msg

    {:noreply, nil}
  end

end

Options

Options are as described in the official documentation, except the following defaults:

  • feed is continuous, this is the only mode supported, trying to change it WILL RAISE A RuntimeError
  • include_docs is true
  • since is now
  • heartbeat is 25, this is needed to keep the connection alive, trying to change it WILL RAISE a RuntimeError
Link to this function changes_unsub(modname)

Unsubscribe the modname watcher from changes in the database.

modname is the module’s name as known to the supervisor, not the actual running module.

Link to this function config_get(node_name \\ nil, section \\ nil, key \\ nil)
config_get(
  node_name :: String.t() | nil,
  section :: String.t() | nil,
  key :: String.t() | nil
) :: couchdb_res()

Set the configuration option for the CouchDB server.

Any option can be nil here, that just goes a level up. If section is nil, the key is also ignored.

Link to this function config_set(node_name, section, key, value)
config_set(
  node_name :: String.t(),
  section :: String.t(),
  key :: String.t(),
  value :: String.t()
) :: couchdb_res()

Set a configuration option for the CouchDB server.

Link to this function couchdb_info()
couchdb_info() :: couchdb_res()

Queries the CouchDB server for some general information about it (e.g. version)

Link to this function db_compact(db_name)
db_compact(db_name :: String.t()) :: :ok | {:error, term()}

Request compaction of the specified database.

If you want to know more, read here

Link to this function db_create(db_name, opts \\ [])
db_create(db_name :: String.t(), opts :: keyword()) :: :ok | {:error, term()}

Create a new database.

The database name must be composed by following next rules:

  • Name must begin with a lowercase letter (a-z)
  • Lowercase characters (a-z)
  • Digits (0-9)
  • Any of the characters _, $, (, ), +, -, and /.

Options

  • shards - number of shards for this database, defaults to 8
Link to this function db_delete(db_name)
db_delete(db_name :: String.t()) :: :ok | {:error, term()}

Deletes the specified database, and all the documents and attachments contained within it.

Link to this function db_exists?(db_name)
db_exists?(db_name :: String.t()) :: {:ok, boolean()} | {:error, term()}

Checks if the specified database exists

Link to this function db_info(db_name)
db_info(db_name :: String.t()) :: couchdb_res()

Get some general information about the database, this includes it’s name, size and clustering information.

Link to this function db_list()
db_list() :: {:ok, [String.t()]} | {:error, term()}

Get the list of all databases, this list includes system databases like _users

Link to this function document_delete_many(id_rev, db)
document_delete_many(id_rev :: [{String.t(), String.t()}], db :: String.t()) ::
  couchdb_res()

Delete multiple documents from the database, id_rev is an array of documents’ {id, revision}.

Internally, this function asks _bulk_docs to set _deleted for those documents

Link to this function document_delete_one(id, rev, db)
document_delete_one(id :: String.t(), rev :: String.t(), db :: String.t()) ::
  :ok | {:error, term()}

Delete a single document from the database.

Link to this function document_find(selector, db, opts \\ [])
document_find(selector :: map(), db :: String.t(), opts :: keyword()) ::
  couchdb_res()

Find a document in the database using the selector spec.

Options

Options and their description are can be found here

Link to this function document_get(id, db, opts \\ [])
document_get(id :: String.t(), db :: String.t(), opts :: keyword()) ::
  couchdb_res()

Get a document from the database.

Options

  • attachments - should the request return full information about attachments (includes full base64 encoded attachments into the request), false by default
Link to this function document_insert_many(docs, db)
document_insert_many(docs :: [map()], db :: String.t()) ::
  {:ok, [map()]} | {:error, term()}

Insert or update multiple documents, for a single document see CouchDBEx.document_insert_one/2.

Internally, this function will make a request to _bulk_docs, that makes it suitable for mass updates too

Link to this function document_insert_one(doc, db)
document_insert_one(doc :: map(), db :: String.t()) :: couchdb_res()

Insert or update a single document, for multiple documents see CouchDBEx.document_insert_many/2.

Link to this function document_list(db, opts \\ [])
document_list(db :: String.t(), opts :: keyword()) :: couchdb_res()

Lists all (or filtered) documents in the database, along with their number

Options are those from _all_docs

Link to this function index_create(index, db, opts \\ [])
index_create(
  index :: map() | [String.t()],
  db :: String.t(),
  opts :: keyword()
) :: couchdb_res()

Create an index.

If index is a list, it is considered a list of indexing fields, otherwise it is used as a full index specification. Options are as specified there too.

Link to this function index_delete(db, ddoc, index_name)
index_delete(db :: String.t(), ddoc :: String.t(), index_name :: String.t()) ::
  :ok | {:error, term()}

Delete the index index_name from the specified design document ddoc.

Link to this function index_list(db)
index_list(db :: String.t()) :: {:ok, [map()], integer()} | {:error, term()}

Lists all indexes and their count.

This function returns it’s data in the following format: {:ok, a list of index specifications, total number of indexes}. Those specifications are described here

Link to this function replicate(src, target, opts \\ [])
replicate(src :: String.t(), target :: String.t(), opts :: keyword()) ::
  couchdb_res()

Replicate a database

Options are as desribed here, except that source and target are already provided

Link to this function uuid_get()
uuid_get() :: {:ok, String.t()} | {:error, term()}

Get a single UUID from the server

Link to this function uuid_get(n)
uuid_get(n :: integer()) :: {:ok, [String.t()]} | {:error, term()}

Get several UUIDs from the server