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 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
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
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
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
copy_delete_doc_option() :: {:rev, String.t} | {:batch, boolean}
delete_attachment_option() :: {:rev, String.t}
fetch_attachment_option() :: {:rev, String.t}
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}
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}
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}
put_attachment_option :: {:rev, String.t} | {:content_type, String.t} | {:content_length, integer}
save_doc_option :: {:new_edits, boolean} | {:batch, boolean} | {:multipart, boolean | String.t}
Link to this section Functions
all_dbs(server :: ICouch.Server.t) :: {:ok, [String.t]} | {:error, term}
Returns a list of all the databases in the CouchDB instance.
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.
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.
Request compaction of the specified database.
compact(db :: ICouch.DB.t, design_doc :: String.t) :: :ok | {:error, term}
Compacts the view indexes associated with the specified design document.
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.
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.
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.
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.
db_exists?(server :: ICouch.Server.t, db_name :: String.t) :: boolean
Tests if a database exists.
db_info(db :: ICouch.DB.t) :: {:ok, map} | {:error, term}
Gets information about the database.
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.
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.
delete_db(db :: ICouch.DB.t) :: :ok | {:error, term}
Deletes the database, and all the documents and attachments contained within it.
delete_db(server :: ICouch.Server.t, db_name :: String.t) :: :ok | {:error, term}
Deletes a database by name.
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.
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.
doc_exists?(db :: ICouch.DB.t, doc_id :: String.t, options :: [open_doc_option]) :: boolean
Tests if a document exists.
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.
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.
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.
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.
get_config(server :: ICouch.Server.t) :: {:ok, map} | {:error, term}
Returns the entire CouchDB server configuration.
CouchDB < 2.0 only.
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.
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.
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.
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.
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.
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.
get_security(db :: ICouch.DB.t) :: {:ok, map} | {:error, term}
Returns the current security object from the specified database.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
read_attachment_data_from_stream(ref, timeout :: integer) :: {:ok, binary} | {:error, term}
Reads all attachment data from the referenced streaming source.
read_doc_from_stream(ref, timeout :: integer) :: {:ok, ICouch.Document.t} | {:error, term}
Builds a full document from the referenced streaming 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.
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.
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.
Creates a server connection.
Equivalent to server_connection("http://127.0.0.1:5984")
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.
server_info(server :: ICouch.Server.t) :: {:ok, map} | {:error, term}
Returns meta information about the server instance.
server_membership(server :: ICouch.Server.t) :: {:ok, map} | {:error, term}
Returns the server’s membership.
CouchDB >= 2.0 only.
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.
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.
set_security(db :: ICouch.DB.t, obj :: map) :: :ok | {:error, term}
Sets the security object for the given database.
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.
Cancels a stream operation.
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.
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.