ICouch v0.5.0 ICouch View Source

Main module of ICouch.

Note: Multipart transmission is the default; you can disable it by setting adding option multipart: false. For saving, it is also possible to use a specific multipart boundary instead of a random one by setting the option to a string instead of boolean.

Link to this section Summary

Functions

Returns a list of all the databases in the CouchDB instance

Opens or creates a database and returns a handle on success

Same as assert_db/2 but returns the database directly on success or raises an error on failure

Request compaction of the specified database

Compacts the view indexes associated with the specified design document

Copies an existing document to a new or existing document

Creates a new local admin user with the given password

Creates a database and returns a handle on success

Same as create_db/2 but returns the database directly on success or raises an error on failure

Tests if a database exists

Gets information about the database

Deletes a configuration value. The returned JSON will be the value of the configuration parameter before it was deleted

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

Deletes a database by name

Deletes a configuration value from a node. The returned JSON will be the value of the configuration parameter before it was deleted

Tests if a document exists

Duplicates an existing document by copying it to a new UUID obtained via get_uuid/1

Commits any recent changes to the specified database to disk

Downloads a document attachment

Same as fetch_attachment/4 but returns the data directly on success or raises an error on failure

Returns the entire CouchDB server configuration

Gets the configuration structure for a single section

Gets a single configuration value from within a specific configuration section

Retrieves the last revision of the document with the specified id

Returns the entire CouchDB node configuration

Gets the configuration structure for a single section of a node

Gets a single configuration value from within a specific configuration section of a node

Returns the current security object from the specified database

Requests one UUID from the CouchDB instance

Same as get_uuid/1 but returns the value directly on success or raises an error on failure

Requests one or more UUIDs from the CouchDB instance

Same as get_uuids/2 but returns the value directly on success or raises an error on failure

Tests if the server is on an admin party

Utility function which calculates the size of the corresponding JSON data of the given parameter

Opens a changes feed in a database

Opens an existing database and returns a handle on success

Same as open_db/2 but returns the database directly on success or raises an error on failure

Opens a document in a database

Same as open_doc/3 but returns the document directly on success or raises an error on failure

Opens a view in a database

Same as open_view/3 but returns the view struct directly on success or raises an error on failure

Reads all attachment data from the referenced streaming source

Builds a full document from the referenced streaming source

Creates a new document or creates a new revision of an existing document

Same as save_doc/3 but returns the updated document directly on success or raises an error on failure

Creates and updates multiple documents at the same time within a single request

Creates a server connection

Creates a server connection

Returns meta information about the server instance

Returns the server’s membership

Updates a configuration value. The new value should be in the correct JSON-serializable format. In response CouchDB sends old value for target section key

Updates a configuration value on a node. The new value should be in the correct JSON-serializable format. In response CouchDB sends old value for target section key

Sets the security object for the given database

Start streaming a document attachment to the given process

Cancels a stream operation

Start streaming a document in a database to the given process

Removes view index files that are no longer required by CouchDB as a result of changed views within design documents

Link to this section Types

Link to this type copy_delete_doc_option() View Source
copy_delete_doc_option() :: {:rev, String.t} | {:batch, boolean}
Link to this type delete_attachment_option() View Source
delete_attachment_option() :: {:rev, String.t}
Link to this type fetch_attachment_option() View Source
fetch_attachment_option() :: {:rev, String.t}
Link to this type open_changes_option() View Source
open_changes_option ::
  {:doc_ids, [String.t]} |
  {:conflicts, boolean} |
  {:descending, boolean} |
  {:filter, String.t} |
  {:include_docs, boolean} |
  {:attachments, boolean} |
  {:att_encoding_info, boolean} |
  {:limit, integer} |
  {:since, String.t | integer} |
  {:style, :main_only | :all_docs} |
  {:view, String.t} |
  {:query_params, map | Keyword.t}
Link to this type open_doc_option() View Source
open_doc_option ::
  {:attachments, boolean} |
  {:att_encoding_info, boolean} |
  {:atts_since, [String.t]} |
  {:conflicts, boolean} |
  {:deleted_conflicts, boolean} |
  {:latest, boolean} |
  {:local_seq, boolean} |
  {:meta, boolean} |
  {:open_revs, [String.t]} |
  {:rev, String.t} |
  {:revs, boolean} |
  {:revs_info, boolean} |
  {:multipart, boolean}
Link to this type open_view_option() View Source
open_view_option ::
  {:conflicts, boolean} |
  {:descending, boolean} |
  {:endkey, String.t} |
  {:endkey_docid, String.t} |
  {:group, boolean} |
  {:group_level, integer} |
  {:include_docs, boolean} |
  {:attachments, boolean} |
  {:att_encoding_info, boolean} |
  {:inclusive_end, boolean} |
  {:key, String.t} |
  {:keys, [String.t]} |
  {:limit, integer} |
  {:reduce, boolean} |
  {:skip, integer} |
  {:stale, :ok | :update_after} |
  {:startkey, String.t} |
  {:startkey_docid, String.t} |
  {:update_seq, boolean}
Link to this type put_attachment_option() View Source
put_attachment_option ::
  {:rev, String.t} |
  {:content_type, String.t} |
  {:content_length, integer}
Link to this type ref() View Source
ref() :: pid | reference
Link to this type save_doc_option() View Source
save_doc_option ::
  {:new_edits, boolean} |
  {:batch, boolean} |
  {:multipart, boolean | String.t}

Link to this section Functions

Link to this function all_dbs(server) View Source
all_dbs(server :: ICouch.Server.t) ::
  {:ok, [String.t]} |
  {:error, term}

Returns a list of all the databases in the CouchDB instance.

Link to this function assert_db(server, db_name) View Source
assert_db(server :: ICouch.Server.t, db_name :: String.t) ::
  {:ok, ICouch.DB.t} |
  {:error, term}

Opens or creates a database and returns a handle on success.

Returns an error if the database could not be created if it was missing.

Implementation note: this tries to create the database first.

Link to this function assert_db!(server, db_name) View Source
assert_db!(server :: ICouch.Server.t, db_name :: String.t) :: ICouch.DB.t

Same as assert_db/2 but returns the database directly on success or raises an error on failure.

Link to this function compact(db) View Source
compact(db :: ICouch.DB.t) :: :ok | {:error, term}

Request compaction of the specified database.

Link to this function compact(db, design_doc) View Source
compact(db :: ICouch.DB.t, design_doc :: String.t) ::
  :ok |
  {:error, term}

Compacts the view indexes associated with the specified design document.

Link to this function copy_doc(db, src_doc, dest_doc_id, options \\ []) View Source
copy_doc(db :: ICouch.DB.t, src_doc :: String.t | ICouch.Document.t | map, dest_doc_id :: String.t, options :: [copy_delete_doc_option]) ::
  {:ok, map} |
  {:error, term}

Copies an existing document to a new or existing document.

Returns a map with the fields "id", "rev" and "ok" on success.

Link to this function create_admin(server, username, password) View Source
create_admin(server :: ICouch.Server.t, username :: String.t, password :: String.t) ::
  {:ok, term} |
  {:error, term}

Creates a new local admin user with the given password.

This works for any CouchDB version by checking if the “_membership” route exists and then using set_config/4 or set_node_config/5 respectively.

Link to this function create_db(server, db_name) View Source
create_db(server :: ICouch.Server.t, db_name :: String.t) ::
  {:ok, ICouch.DB.t} |
  {:error, term}

Creates a database and returns a handle on success.

Fails if the database already exists.

Link to this function create_db!(server, db_name) View Source
create_db!(server :: ICouch.Server.t, db_name :: String.t) :: ICouch.DB.t

Same as create_db/2 but returns the database directly on success or raises an error on failure.

Link to this function db_exists?(server, db_name) View Source
db_exists?(server :: ICouch.Server.t, db_name :: String.t) :: boolean

Tests if a database exists.

Link to this function db_info(db) View Source
db_info(db :: ICouch.DB.t) :: {:ok, map} | {:error, term}

Gets information about the database.

Link to this function delete_attachment(db, doc, filename, options \\ []) View Source
delete_attachment(db :: ICouch.DB.t, doc :: String.t | map, filename :: String.t, options :: [delete_attachment_option]) ::
  {:ok, map} |
  {:error, term}

Deletes a document attachment.

A rev number is required if only the document ID is given instead of the document itself.

Link to this function delete_config(server, section, key) View Source
delete_config(server :: ICouch.Server.t, section :: String.t, key :: String.t) ::
  {:ok, term} |
  {:error, term}

Deletes a configuration value. The returned JSON will be the value of the configuration parameter before it was deleted.

CouchDB < 2.0 only.

Link to this function delete_db(db) View Source
delete_db(db :: ICouch.DB.t) :: :ok | {:error, term}

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

Link to this function delete_db(server, db_name) View Source
delete_db(server :: ICouch.Server.t, db_name :: String.t) ::
  :ok |
  {:error, term}

Deletes a database by name.

Link to this function delete_doc(db, doc, options \\ []) View Source
delete_doc(db :: ICouch.DB.t, doc :: String.t | ICouch.Document.t | map, options :: [copy_delete_doc_option]) ::
  {:ok, map} |
  {:error, term}

Deletes a document.

This marks the specified document as deleted by adding a field _deleted with the value true.

A rev number is required if only the document ID is given instead of the document itself.

Link to this function delete_node_config(server, node_name, section, key) View Source
delete_node_config(server :: ICouch.Server.t, node_name :: String.t, section :: String.t, key :: String.t) ::
  {:ok, term} |
  {:error, term}

Deletes a configuration value from a node. The returned JSON will be the value of the configuration parameter before it was deleted.

CouchDB >= 2.0 only.

Link to this function doc_exists?(db, doc_id, options \\ []) View Source
doc_exists?(db :: ICouch.DB.t, doc_id :: String.t, options :: [open_doc_option]) :: boolean

Tests if a document exists.

Link to this function dup_doc(db, src_doc, options \\ []) View Source
dup_doc(db :: ICouch.DB.t, src_doc :: String.t | ICouch.Document.t | map, options :: [copy_delete_doc_option]) ::
  {:ok, map} |
  {:error, term}

Duplicates an existing document by copying it to a new UUID obtained via get_uuid/1.

Returns a map with the fields "id", "rev" and "ok" on success.

Link to this function ensure_full_commit(db) View Source
ensure_full_commit(db :: ICouch.DB.t) ::
  {:ok, instance_start_time :: integer | nil} |
  {:error, term}

Commits any recent changes to the specified database to disk.

Link to this function fetch_attachment(db, doc, filename, options \\ []) View Source
fetch_attachment(db :: ICouch.DB.t, doc :: String.t | map, filename :: String.t, options :: [fetch_attachment_option]) ::
  {:ok, binary} |
  {:error, term}

Downloads a document attachment.

Link to this function fetch_attachment!(db, doc, filename, options \\ []) View Source
fetch_attachment!(db :: ICouch.DB.t, doc :: String.t | map, filename :: String.t, options :: [fetch_attachment_option]) ::
  binary |
  ref

Same as fetch_attachment/4 but returns the data directly on success or raises an error on failure.

Link to this function get_config(server) View Source
get_config(server :: ICouch.Server.t) ::
  {:ok, map} |
  {:error, term}

Returns the entire CouchDB server configuration.

CouchDB < 2.0 only.

Link to this function get_config(server, section) View Source
get_config(server :: ICouch.Server.t, section :: String.t) ::
  {:ok, map} |
  {:error, term}

Gets the configuration structure for a single section.

CouchDB < 2.0 only.

Link to this function get_config(server, section, key) View Source
get_config(server :: ICouch.Server.t, section :: String.t, key :: String.t) ::
  {:ok, map} |
  {:error, term}

Gets a single configuration value from within a specific configuration section.

CouchDB < 2.0 only.

Link to this function get_doc_rev(db, doc_id) View Source
get_doc_rev(db :: ICouch.DB.t, doc_id :: String.t) ::
  {:ok, String.t} |
  {:error, term}

Retrieves the last revision of the document with the specified id.

Link to this function get_node_config(server, node_name) View Source
get_node_config(server :: ICouch.Server.t, node_name :: String.t) ::
  {:ok, map} |
  {:error, term}

Returns the entire CouchDB node configuration.

CouchDB >= 2.0 only.

Link to this function get_node_config(server, node_name, section) View Source
get_node_config(server :: ICouch.Server.t, node_name :: String.t, section :: String.t) ::
  {:ok, map} |
  {:error, term}

Gets the configuration structure for a single section of a node.

CouchDB >= 2.0 only.

Link to this function get_node_config(server, node_name, section, key) View Source
get_node_config(server :: ICouch.Server.t, node_name :: String.t, section :: String.t, key :: String.t) ::
  {:ok, map} |
  {:error, term}

Gets a single configuration value from within a specific configuration section of a node.

CouchDB >= 2.0 only.

Link to this function get_security(db) View Source
get_security(db :: ICouch.DB.t) :: {:ok, map} | {:error, term}

Returns the current security object from the specified database.

Link to this function get_uuid(server) View Source
get_uuid(server :: ICouch.Server.t) ::
  {:ok, String.t} |
  {:error, term}

Requests one UUID from the CouchDB instance.

Note that this is not strictly UUID compliant; it will in fact return a 32 character hexadecimal string.

Link to this function get_uuid!(server) View Source
get_uuid!(server :: ICouch.Server.t) :: String.t

Same as get_uuid/1 but returns the value directly on success or raises an error on failure.

Link to this function get_uuids(server, count) View Source
get_uuids(server :: ICouch.Server.t, count :: integer) ::
  {:ok, [String.t]} |
  {:error, term}

Requests one or more UUIDs from the CouchDB instance.

Note that this is not strictly UUID compliant; it will in fact return a list of 32 character hexadecimal strings.

Link to this function get_uuids!(server, count) View Source
get_uuids!(server :: ICouch.Server.t, count :: integer) :: [String.t]

Same as get_uuids/2 but returns the value directly on success or raises an error on failure.

Link to this function has_admin_party?(server) View Source
has_admin_party?(server :: ICouch.Server.t) :: boolean

Tests if the server is on an admin party.

This is achieved by temporarily stripping credentials from the server struct and trying to call server_membership/1 (followed by a call to get_config(server, "couchdb", "database_dir") if the server does not have that route).

Utility function which calculates the size of the corresponding JSON data of the given parameter.

Since UTF-8 strings are to be used everywhere, this should be accurate.

Link to this function open_changes(db, options \\ []) View Source
open_changes(db :: ICouch.DB.t, options :: [open_changes_option]) :: ICouch.Changes.t

Opens a changes feed in a database.

This always succeeds and returns an unfetched ICouch.Changes.t struct.

Note that when setting the doc_ids option, any given filter option will be ignored while fetching changes.

See also: ChangesFollower

Link to this function open_db(server, db_name) View Source
open_db(server :: ICouch.Server.t, db_name :: String.t) ::
  {:ok, ICouch.DB.t} |
  {:error, term}

Opens an existing database and returns a handle on success.

Does check if the database exists.

Link to this function open_db!(server, db_name) View Source
open_db!(server :: ICouch.Server.t, db_name :: String.t) :: ICouch.DB.t

Same as open_db/2 but returns the database directly on success or raises an error on failure.

Link to this function open_doc(db, doc_id, options \\ []) View Source
open_doc(db :: ICouch.DB.t, doc_id :: String.t, options :: [open_doc_option]) ::
  {:ok, ICouch.Document.t} |
  {:error, term}

Opens a document in a database.

Link to this function open_doc!(db, doc_id, options \\ []) View Source
open_doc!(db :: ICouch.DB.t, doc_id :: String.t, options :: [open_doc_option]) :: map

Same as open_doc/3 but returns the document directly on success or raises an error on failure.

Link to this function open_view(db, name, options \\ []) View Source
open_view(db :: ICouch.DB.t, name :: String.t, options :: [open_view_option]) ::
  {:ok, ICouch.View.t} |
  {:error, term}

Opens a view in a database.

This will check if the design document exists and return a ICouch.View.t struct which can be iterated using Enum functions. The returned view is unfetched.

The name should be in the form design_doc_name/view_name except for “_all_docs”.

Note that the “_all_docs” view is not checked for existence.

Link to this function open_view!(db, doc, options \\ []) View Source
open_view!(db :: ICouch.DB.t, name :: String.t, options :: [open_view_option]) :: ICouch.View.t

Same as open_view/3 but returns the view struct directly on success or raises an error on failure.

Link to this function put_attachment(db, doc, filename, body, options \\ []) View Source
put_attachment(db :: ICouch.DB.t, doc :: String.t | map, filename :: String.t, body :: ICouch.Server.body, options :: [put_attachment_option]) ::
  {:ok, map} |
  {:error, term}

Uploads a document attachment.

In order to stream the attachment body, a function of arity 0 or 1 can be provided that should return {:ok, data} or :eof.

A rev number is required if only the document ID is given instead of the document itself.

Link to this function read_attachment_data_from_stream(ref, timeout) View Source
read_attachment_data_from_stream(ref, timeout :: integer) ::
  {:ok, binary} |
  {:error, term}

Reads all attachment data from the referenced streaming source.

Link to this function read_doc_from_stream(ref, timeout \\ 30000) View Source
read_doc_from_stream(ref, timeout :: integer) ::
  {:ok, ICouch.Document.t} |
  {:error, term}

Builds a full document from the referenced streaming source.

Link to this function save_doc(db, doc, options \\ []) View Source
save_doc(db :: ICouch.DB.t, doc :: map | ICouch.Document.t, options :: [save_doc_option]) ::
  {:ok, ICouch.Document.t} |
  {:error, term}

Creates a new document or creates a new revision of an existing document.

If the document does not have an “_id” property, the function will obtain a new UUID via get_uuid/1.

Returns the saved document with updated revision on success. If a map is passed instead of a Document struct, it will be converted to a ICouch.Document.t first.

Link to this function save_doc!(db, doc, options \\ []) View Source
save_doc!(db :: ICouch.DB.t, doc :: map | ICouch.Document.t, options :: [save_doc_option]) :: map

Same as save_doc/3 but returns the updated document directly on success or raises an error on failure.

Link to this function save_docs(db, docs, options \\ []) View Source
save_docs(db :: ICouch.DB.t, docs :: [map | ICouch.Document.t], options :: [save_doc_option]) ::
  {:ok, [map]} |
  {:error, term}

Creates and updates multiple documents at the same time within a single request.

It is possible to mix Document structs and plain maps.

Link to this function server_connection() View Source
server_connection() :: ICouch.Server.t

Creates a server connection.

Equivalent to server_connection("http://127.0.0.1:5984")

Link to this function server_connection(uri, options \\ []) View Source
server_connection(uri :: String.t | URI.t, options :: [ICouch.Server.option]) :: ICouch.Server.t

Creates a server connection.

Pass either an URI string or URI struct. Basic authorization is supported via URI "http://user:pass@example.com:5984/" or via options. Note that omitting the port number will result in port 80 (or 443) as per URI standards.

The given URI acts as base URI for requests; any CouchDB API calls will be relative to it. That said, the last path element (usually) should be terminated with a / due to the way how relative URIs work. See (RFC 3986)[http://tools.ietf.org/html/rfc3986#section-5.2].

Also note that this does not actually establish a connection; use server_info/1 to test connectivity.

The available options are mostly equivalent to ibrowse’s, but use the string type where applicable. Not all options are supported. See the ICouch.Server module for a list.

Link to this function server_info(server) View Source
server_info(server :: ICouch.Server.t) ::
  {:ok, map} |
  {:error, term}

Returns meta information about the server instance.

Link to this function server_membership(server) View Source
server_membership(server :: ICouch.Server.t) ::
  {:ok, map} |
  {:error, term}

Returns the server’s membership.

CouchDB >= 2.0 only.

Link to this function set_config(server, section, key, value) View Source
set_config(server :: ICouch.Server.t, section :: String.t, key :: String.t, value :: term) ::
  {:ok, term} |
  {:error, term}

Updates a configuration value. The new value should be in the correct JSON-serializable format. In response CouchDB sends old value for target section key.

CouchDB < 2.0 only.

Link to this function set_node_config(server, node_name, section, key, value) View Source
set_node_config(server :: ICouch.Server.t, node_name :: String.t, section :: String.t, key :: String.t, value :: term) ::
  {:ok, term} |
  {:error, term}

Updates a configuration value on a node. The new value should be in the correct JSON-serializable format. In response CouchDB sends old value for target section key.

CouchDB >= 2.0 only.

Link to this function set_security(db, obj) View Source
set_security(db :: ICouch.DB.t, obj :: map) ::
  :ok |
  {:error, term}

Sets the security object for the given database.

Link to this function stream_attachment(db, doc, filename, stream_to, options \\ []) View Source
stream_attachment(db :: ICouch.DB.t, doc :: String.t | map, filename :: String.t, stream_to :: pid, options :: [fetch_attachment_option]) ::
  {:ok, ref} |
  {:error, term}

Start streaming a document attachment to the given process.

See ICouch.StreamChunk and ICouch.StreamEnd. The returned value will be the stream reference.

Link to this function stream_cancel(ref) View Source
stream_cancel(ref) :: :ok

Cancels a stream operation.

Link to this function stream_doc(db, doc_id, stream_to, options \\ []) View Source
stream_doc(db :: ICouch.DB.t, doc_id :: String.t, stream_to :: pid, options :: [open_doc_option]) ::
  {:ok, ref} |
  {:error, term}

Start streaming a document in a database to the given process.

See ICouch.StreamChunk and ICouch.StreamEnd. The returned value will be the stream reference. If attachments are requested, they will be streamed separately, even if the server does not support multipart.

Link to this function view_cleanup(db) View Source
view_cleanup(db :: ICouch.DB.t) :: :ok | {:error, term}

Removes view index files that are no longer required by CouchDB as a result of changed views within design documents.