couchex v0.8.0 Couchex
Wrapper around the couchbeam erlang couchdb client
Summary
Functions
Returns all documents in a database
Returns a list of all databases
Compacts a database
Compacts the view index
Creates a database. The database must NOT exist
- CouchDB 2.0 only - Creates an index
Checks if database exist
Returns database info
Delete attachment from document
Deletes a database. The database must exist
Deletes a database. The database must exist
Delete a document
Deletes a list of documents
Returns true if document exists
Fetch attachment from document
Fetch view
- CouchDB 2.0 only - Retreives all documents via mango query
Follow database changes
Returns current document revision
Opens a database
Retreives document as map, by id with or without revision
Put an attachment to document
Replicates a database from source to target
Save and update a document
Returns a server connection
Returns basic info about server
Returns a single server generated uuid
Returns a total of number
server generated uuids
Functions
Returns all documents in a database
Examples
Couchex.all(db)
#=> [
%{
"doc" => %{"_id" => "doc_id_1", "_rev" => "...", "foo" => "bar"},
"id" => "doc_id_1",
"key" => "doc_id_1",
"value" => %{"rev" => "..."}
},
%{"doc" => %{"_id" => "doc_id_2", ...
]
Returns a list of all databases
Examples
Couchex.all_dbs(server)
#=> {:ok, ["_replicator", "_users", "some_db", ...]}
Compacts a database.
Examples
{:ok, db} = Couchex.open_db(server, "couchex")
Couchex.compact(db)
#=> :ok
Compacts the view index.
Examples
{:ok, db} = Couchex.open_db(server, "couchex")
Couchex.compact(db, "design_name")
#=> :ok
Creates a database. The database must NOT exist
Examples
Couchex.create_db(server, "couchex")
#=> {:db, server, "couchex", [basic_auth: {"username", "password"}]}}
Couchex.create_db(server, "couchex")
#=> {:error, :db_exists}
- CouchDB 2.0 only - Creates an index
Examples
index = %{ "name" => "name-index", "type" => "json", "index" => %{ "fields" => [ %{ "key": "asc" } ] } }
Couchex.create_index(db, index)
#=> {:ok, %{id: "id", name: "name-index", status: :created}}
Returns database info.
Examples
{:ok, db} = Couchex.open_db(server, "couchex")
Couchex.db_info(db)
#=> %{"committed_update_seq" => 0, "compact_running" => false, "data_size" => 227,
"db_name" => "couchex", "disk_format_version" => 6, "disk_size" => 306,
"doc_count" => 1, "doc_del_count" => 0,
"instance_start_time" => "1423503379138489", "purge_seq" => 0,
"update_seq" => 1}
Delete attachment from document
This method is idempotent, and will increment the document revision, even though the attachment isn’t present(e.g. already deleted)
Examples
attachment_name = "file.txt"
Couchex.delete_attachment(db, %{id: "18c359e463c37525e0ff484dcc0003b7"}, attachment_name)
#=> {:ok, %{"id" => "18c359e463c37525e0ff484dcc0003b7", "rev" => "4-ebe18f0e4f4c3c717a9e9291bc2465b3"}}
Couchex.delete_attachment(db, %{id: "18c359e463c37525e0ff484dcc0003b7", rev: "3-ebe18f0e4f4c3c717a9e9291bc2465b3"}, attachment_name)
#=> {:ok, %{"id" => "18c359e463c37525e0ff484dcc0003b7", "rev" => "4-ebe18f0e4f4c3c717a9e9291bc2465b3"}}
Deletes a database. The database must exist
Examples
{:ok, db} = Couchex.open_db(server, "couchex")
#=> {:ok, {:db, server, "couchex", []}}
Couchex.delete_db(db)
#=> {:ok, :db_deleted}
Couchex.delete_db(db)
#=> {:error, :not_found}
Deletes a database. The database must exist
Examples
Couchex.delete_db(server, "couchex")
#=> {:ok, :db_deleted}
Couchex.delete_db(server, "couchex")
#=> {:error, :not_found}
Delete a document
Examples
Couchex.delete_doc(db, %{id: "18c359e463c37525e0ff484dcc0003b7", rev: "1-59414e77c768bc202142ac82c2f129de"})
#=> %{"id" => "18c359e463c37525e0ff484dcc0003b7", "ok" => true, "rev" => "2-9b2e3bcc3752a3a952a3570b2ed4d27e"}
Deletes a list of documents
Examples
Couchex.delete_docs(db, [%{id: "18c359e463c37525e0ff484dcc0003b7", rev: "1-59414e77c768bc202142ac82c2f129de"}])
#=> [%{"id" => "18c359e463c37525e0ff484dcc0003b7", "ok" => true, "rev" => "2-9b2e3bcc3752a3a952a3570b2ed4d27e"}]
Returns true if document exists
Examples
Couchex.doc_exists?(db, "EXISTING_DOC_ID")
#=> true
Couchex.doc_exists?(db, "NONE_EXISTING_DOC_ID")
#=> false
Fetch attachment from document
Examples
doc_id = "18c359e463c37525e0ff484dcc0003b7"
attachment_name = "file.txt"
Couchex.fetch_attachment(db, doc_id, attachment_name)
#=> {:ok, "SOME DATA - HERE IT'S TEXT"}
Fetch view
Examples
{:ok, res} = Couchex.fetch_view(db, {"lists","company_users_by_income"},[:group])
When having a design doc like this,
design_doc = %{
"_id" => "_design/lists",
"language": "javascript",
"views": %{
"by_customer_id": %{
"map": "function(doc) { emit(doc.customer_id, doc);}"
}
}
}
fetch docs by customer id
{:ok, res} = Couchex.fetch_view(db, {"lists","by_customer_id"},[key: customer_id])
- CouchDB 2.0 only - Retreives all documents via mango query
Examples
query = %{
"selector": %{
"_id": %{
"$gt": nil
}
}
}
Couchex.find(db, query)
#=> %{ docs: [%{"_id" => "..."}, ...], warning: <ONLY IF WARNING SENT FROM SERVER> }
Follow database changes
Examples
def changes_fun(stream_ref) do
receive do
{stream_ref, {:done, last_seq}} ->
Logger.info "Stopped at seq: #{inspect last_seq}"
:ok
{stream_ref, {:change, change}} ->
Logger.info "Change: #{inspect change}"
changes_fun(stream_ref)
{stream_ref, error}->
Log.error "#{inspect error}"
msg ->
Logger.warn "#{inspect msg}"
end
end
Couchex.follow(db, [:continuous, :heartbeat])
#=> {:ok, <stream_ref>}
changes_fun(<stream_ref>)
Returns current document revision
Examples
Couchex.lookup_doc_rev(db, "18c359e463c37525e0ff484dcc0003b7")
#=> {:ok, "1-59414e77c768bc202142ac82c2f129de"}
Opens a database
If credentials were passed during server_connection, they will be passed on to open_db. They will however be overwritten by the credentials applied to open_db
Examples
Couchex.open_db(server, "couchex")
#=> {:ok, {:db, server, "couchex", []}}
Couchex.open_db(server, "couchex", [{:basic_auth, {"username", "password"}}])
#=> {:ok, {:db, server, "couchex", [{:basic_auth, {"username", "password"}}]}}
Retreives document as map, by id with or without revision
Examples
Couchex.open_doc(db, %{id: id})
#=> {:ok, %{"_id" => id, "_rev" => rev, ...}}
Couchex.open_doc(db, %{id: id, rev: revision})
#=> {:ok, %{"_id" => id, "_rev" => rev, ...}}
Put an attachment to document
Examples
attachment = %{ name: "image.png", data: "....", content_type: "image/png" }
Couchex.put_attachment(db, %{id: id}, attachment) # latest revision
#=> {:ok, %{"id" => "18c359e463c37525e0ff484dcc0003b7", "rev" => "3-ebe18f0e4f4c3c717a9e9291bc2465b3"}}
doc_id = "18c359e463c37525e0ff484dcc0003b7"
revision = "1-59414e77c768bc202142ac82c2f129de"
content_type = Couchex.MIME.type("txt") # => "text/plain"
attachment = %{ name: "file.txt", data: "SOME DATA - HERE IT'S TEXT", content_type: content_type }
Couchex.put_attachment(db, %{id: doc_id, rev: revision}, attachment)
#=> {:ok, %{"id" => "18c359e463c37525e0ff484dcc0003b7", "rev" => "3-ebe18f0e4f4c3c717a9e9291bc2465b3"}}
Replicates a database from source to target
Examples
create_target
param, target db is created if not already present
continuous
param, replication runs continuously until server restart
Couchex.replicate(server, %{source: "sourcedb", target: "targetdb", create_target: true})
#=> {:ok, %{"history" => [...], "ok" => true, "replication_id_version" => 3, "session_id" => "b3457b342b2eb31ea0f85e77bac03a66", "source_last_seq" => 16}}
Couchex.replicate(server, %{source: "https://user:pass@sourcedb", target: "targetdb", create_target: true})
#=> {:ok, resp}
Couchex.replicate(server, %{source: "https://user:pass@sourcedb", target: "http://user:pass@targetdb", create_target: true})
#=> {:ok, resp}
Couchex.replicate(server, %{source: "https://user:pass@sourcedb", target: "http://user:pass@targetdb", create_target: true, continuous: true})
#=> #=> {:ok, %{"Cache-Control" => "must-revalidate", "Content-Length" => "84", "Content-Type" => "application/json", "Date" => "Mon, 09 Feb 2015 16:24:19 GMT", "Server" => "CouchDB/1.5.0 (Erlang OTP/R16B03)"}}
Save and update a document
Update a document, by using an existing document id
Please remark the use of %{"_id" => "ID", ...}
and not %{"_id": "ID", ...}
, the latter will not work
Examples
Couchex.save_doc(db, %{"key" => "value"}) # Couch auto creates id
#=> %{"_id" => "c1cdba4b7d7a963b9ca7c5445684679f", "_rev" => "1-59414e77c768bc202142ac82c2f129de", "key" => "value"}
Couchex.save_doc(db, %{"_id" => "FIRST_ID", "key" => "value"}) # User defined id
#=> %{"_id" => "FIRST_ID", "_rev" => "1-59414e77c768bc202142ac82c2f129de", "key" => "value"}
Returns a server connection
Examples
Couchex.server_connection("url")
#=> {:server, "url", []}
Couchex.server_connection(@couchdb_url, [{:basic_auth, {"username", "password"}}])
#=> {:server, "url", [{:basic_auth, {"username", "password"}}]}
Returns basic info about server
Examples
Couchex.server_info(server)
#=> %{"couchdb" => "Welcome", "uuid" => "c1cdba4b7d7a963b9ca7c5445684679f", "vendor" => {[{"version", "1.5.0-1"}, {"name", "Homebrew"}]}, "version" => "1.5.0"}