ICouch v0.6.2 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/3
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/3
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 document attachment.
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 document.
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.
Gets the current revision limit setting.
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 several documents in a database.
Same as open_docs/3
but returns the documents 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.
Uploads a document attachment.
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.
Gets the current revision limit setting.
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
delete_attachment_option()
View Sourcedelete_attachment_option() :: {:rev, String.t()}
fetch_attachment_option()
View Sourcefetch_attachment_option() :: {:rev, String.t()}
open_changes_option()
View Sourceopen_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()}
open_doc_option()
View Sourceopen_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()}
open_view_option()
View Sourceopen_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 section Functions
all_dbs(server)
View Sourceall_dbs(server :: ICouch.Server.t()) :: {:ok, [String.t()]} | {:error, term()}
Returns a list of all the databases in the CouchDB instance.
assert_db(server, db_name, options \\ [])
View Sourceassert_db( server :: ICouch.Server.t(), db_name :: String.t(), options :: [create_db_option()] ) :: {: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.
assert_db!(server, db_name, options \\ [])
View Sourceassert_db!( server :: ICouch.Server.t(), db_name :: String.t(), options :: [create_db_option()] ) :: ICouch.DB.t()
Same as assert_db/3
but returns the database directly on success or raises
an error on failure.
compact(db)
View Sourcecompact(db :: ICouch.DB.t()) :: :ok | {:error, term()}
Request compaction of the specified database.
compact(db, design_doc)
View Sourcecompact(db :: ICouch.DB.t(), design_doc :: String.t()) :: :ok | {:error, term()}
Compacts the view indexes associated with the specified design document.
copy_doc(db, src_doc, dest_doc_id, options \\ [])
View Sourcecopy_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.
create_admin(server, username, password)
View Sourcecreate_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.
create_db(server, db_name, options \\ [])
View Sourcecreate_db( server :: ICouch.Server.t(), db_name :: String.t(), options :: [create_db_option()] ) :: {:ok, ICouch.DB.t()} | {:error, term()}
Creates a database and returns a handle on success.
Fails if the database already exists.
create_db!(server, db_name, options \\ [])
View Sourcecreate_db!( server :: ICouch.Server.t(), db_name :: String.t(), options :: [create_db_option()] ) :: ICouch.DB.t()
Same as create_db/3
but returns the database directly on success or raises
an error on failure.
db_exists?(server, db_name)
View Sourcedb_exists?(server :: ICouch.Server.t(), db_name :: String.t()) :: boolean()
Tests if a database exists.
db_info(db)
View Sourcedb_info(db :: ICouch.DB.t()) :: {:ok, map()} | {:error, term()}
Gets information about the database.
delete_attachment(db, doc, filename, options \\ [])
View Sourcedelete_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.
delete_config(server, section, key)
View Sourcedelete_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.
delete_db(db)
View Sourcedelete_db(db :: ICouch.DB.t()) :: :ok | {:error, term()}
Deletes the database, and all the documents and attachments contained within it.
delete_db(server, db_name)
View Sourcedelete_db(server :: ICouch.Server.t(), db_name :: String.t()) :: :ok | {:error, term()}
Deletes a database by name.
delete_doc(db, doc, options \\ [])
View Sourcedelete_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.
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.
doc_exists?(db, doc_id, options \\ [])
View Sourcedoc_exists?( db :: ICouch.DB.t(), doc_id :: String.t(), options :: [open_doc_option()] ) :: boolean()
Tests if a document exists.
dup_doc(db, src_doc, options \\ [])
View Sourcedup_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.
ensure_full_commit(db)
View Sourceensure_full_commit(db :: ICouch.DB.t()) :: {:ok, instance_start_time :: integer() | nil} | {:error, term()}
Commits any recent changes to the specified database to disk.
fetch_attachment(db, doc, filename, options \\ [])
View Sourcefetch_attachment( db :: ICouch.DB.t(), doc :: String.t() | map(), filename :: String.t(), options :: [fetch_attachment_option()] ) :: {:ok, binary()} | {:error, term()}
Downloads a document attachment.
fetch_attachment!(db, doc, filename, options \\ [])
View Sourcefetch_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.
get_config(server)
View Sourceget_config(server :: ICouch.Server.t()) :: {:ok, map()} | {:error, term()}
Returns the entire CouchDB server configuration.
CouchDB < 2.0 only.
get_config(server, section)
View Sourceget_config(server :: ICouch.Server.t(), section :: String.t()) :: {:ok, map()} | {:error, term()}
Gets the configuration structure for a single section.
CouchDB < 2.0 only.
get_config(server, section, key)
View Sourceget_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.
get_doc_rev(db, doc_id)
View Sourceget_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.
get_node_config(server, node_name)
View Sourceget_node_config(server :: ICouch.Server.t(), node_name :: String.t()) :: {:ok, map()} | {:error, term()}
Returns the entire CouchDB node configuration.
CouchDB >= 2.0 only.
get_node_config(server, node_name, section)
View Sourceget_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.
Gets a single configuration value from within a specific configuration section of a node.
CouchDB >= 2.0 only.
get_revs_limit(db)
View Sourceget_revs_limit(db :: ICouch.DB.t()) :: {:ok, integer()} | {:error, term()}
Gets the current revision limit setting.
CouchDB >= 2.0 only.
get_security(db)
View Sourceget_security(db :: ICouch.DB.t()) :: {:ok, map()} | {:error, term()}
Returns the current security object from the specified database.
get_uuid(server)
View Sourceget_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.
get_uuid!(server)
View Sourceget_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.
get_uuids(server, count)
View Sourceget_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.
get_uuids!(server, count)
View Sourceget_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.
has_admin_party?(server)
View Sourcehas_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.
open_changes(db, options \\ [])
View Sourceopen_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
open_db(server, db_name)
View Sourceopen_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.
open_db!(server, db_name)
View Sourceopen_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.
open_doc(db, doc_id, options \\ [])
View Sourceopen_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.
open_doc!(db, doc_id, options \\ [])
View Sourceopen_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.
open_docs(db, doc_ids_revs, options \\ [])
View Sourceopen_docs( db :: ICouch.DB.t(), doc_ids_revs :: [ String.t() | {String.t(), String.t()} | {String.t(), String.t(), String.t()} | map() ], options :: [open_docs_option()] ) :: {:ok, [ICouch.Document.t()]} | {:error, term()}
Opens several documents in a database.
The parameter can be a list of strings (document IDs) or tuples of two strings (document ID + revision) or tuples of three strings (document ID + revision + attributes since) or maps (see CouchDB documentation) or any mix of those.
CouchDB >= 2.0 only. You can similar results using the "_all_docs" view on CouchDB < 2.0.
open_docs!(db, doc_ids_revs, options \\ [])
View Sourceopen_docs!( db :: ICouch.DB.t(), doc_ids_revs :: [ String.t() | {String.t(), String.t()} | {String.t(), String.t(), String.t()} | map() ], options :: [open_docs_option()] ) :: [ICouch.Document.t()]
Same as open_docs/3
but returns the documents directly on success or raises
an error on failure.
open_view(db, name, options \\ [])
View Sourceopen_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", "_design_docs" and "_local_docs".
Note that the "_all_docs", "_design_docs" and "_local_docs" view is not checked for existence; the latter two are only available on CouchDB >= 2.0.
open_view!(db, doc, options \\ [])
View Sourceopen_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.
put_attachment(db, doc, filename, body, options \\ [])
View Sourceput_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.
Reads all attachment data from the referenced streaming source.
read_doc_from_stream(ref, timeout \\ 30000)
View Sourceread_doc_from_stream(ref(), timeout :: integer()) :: {:ok, ICouch.Document.t()} | {:error, term()}
Builds a full document from the referenced streaming source.
save_doc(db, doc, options \\ [])
View Sourcesave_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.
save_doc!(db, doc, options \\ [])
View Sourcesave_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.
save_docs(db, docs, options \\ [])
View Sourcesave_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.
Creates a server connection.
Equivalent to server_connection("http://127.0.0.1:5984")
server_connection(uri, options \\ [])
View Sourceserver_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.
server_info(server)
View Sourceserver_info(server :: ICouch.Server.t()) :: {:ok, map()} | {:error, term()}
Returns meta information about the server instance.
server_membership(server)
View Sourceserver_membership(server :: ICouch.Server.t()) :: {:ok, map()} | {:error, term()}
Returns the server's membership.
CouchDB >= 2.0 only.
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.
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.
set_revs_limit(db, limit)
View Sourceset_revs_limit(db :: ICouch.DB.t(), limit :: integer()) :: :ok | {:error, term()}
Gets the current revision limit setting.
CouchDB >= 2.0 only.
set_security(db, obj)
View Sourceset_security(db :: ICouch.DB.t(), obj :: map()) :: :ok | {:error, term()}
Sets the security object for the given database.
stream_attachment(db, doc, filename, stream_to, options \\ [])
View Sourcestream_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.
Cancels a stream operation.
stream_doc(db, doc_id, stream_to, options \\ [])
View Sourcestream_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.
view_cleanup(db)
View Sourceview_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.