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
Upload an attachment to the document
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
Create an index
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 section Functions
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 theContent-Type
header for the request.
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
iscontinuous
, this is the only mode supported, trying to change it WILL RAISE A RuntimeErrorinclude_docs
istrue
since
isnow
heartbeat
is25
, this is needed to keep the connection alive, trying to change it WILL RAISE a RuntimeError
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.
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.
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.
Queries the CouchDB server for some general information about it (e.g. version)
Request compaction of the specified database.
If you want to know more, read here
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
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
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
Delete a single document from the database.
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
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
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
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
.
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
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.
Delete the index index_name
from the specified design document ddoc
.
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
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
Get a single UUID from the server
Get several UUIDs from the server