Crate couchdb [−] [src]

The couchdb crate provides low-level access to individual HTTP actions—e.g., PUT database, GET document, etc. It handles the menial task of sending requests and receiving responses, thereby allowing application programmers to focus on their business logic.

This documentation has been written assuming the application programmer is familiar with the CouchDB API. Descriptions of types, methods, etc. in the couchdb crate should provide just enough information for the programmer to map the crate's concepts onto the CouchDB API and then use the CouchDB documentation as needed to fill in remaining details. Most names in the crate API are identical to the names used in the CouchDB API so as to make this mapping straightforward. There's also a table, below, that shows the mapping at a high level.

One key difference between the couchdb crate's API and the CouchDB API is the crate provides stronger type-safety beyond working with raw strings. For example, applications get and put documents using structured types, and other types, such as revisions and views, are strongly typed as well.

To deal with JSON, the couchdb crate relies on Serde and its traits serde::Serialize and serde::Deserialize. These traits are fundamental to the crate's API—they are not mere implementation details. As such, applications must use these traits when working with documents, views, or any type that is JSON-encoded in the CouchDB API.

Example: Create a document, read a document

This example shows how the couchdb crates thinly wraps the CouchDB API.

The following program (1) constructs a Client with which to connect to the CouchDB server, (2) creates a database (via the put_database method), (3) creates a document within that database (via the post_database method), and (4) reads the new document (via the get_document method).

extern crate couchdb;
extern crate serde_json;

// The `Client` type is the entry point for sending all HTTP requests to the
// CouchDB server.
let client = couchdb::Client::new("http://couchdb-server:5984/").unwrap();

// PUT http://couchdb-server:5984/baseball
client.put_database("/baseball").run().unwrap();

// POST http://couchdb-server:5984/baseball
let content = serde_json::builder::ObjectBuilder::new()
                  .insert("name", "Babe Ruth")
                  .insert("career_hr", 714)
                  .unwrap();
let (id, rev) = client.post_database("/baseball", &content)
                      .run()
                      .unwrap();

// GET http://couchdb-server:5984/baseball/<doc_id>
let doc = client.get_document(("/baseball", id.clone()))
                .run()
                .unwrap()
                .unwrap();
assert_eq!(id, doc.id);
assert_eq!(rev, doc.rev);
assert_eq!(content, doc.into_content().unwrap());

CouchDB API overview

This table shows the mapping from each CouchDB API action to the Client method that performs that action.

In the couchdb crate, the Client type is the principal type for communicating with a CouchDB server. All HTTP requests to the CouchDB server go through a Client instance.

URI path	Method	`Client` method	Description
`/`	GET	`get_root`	Get server version and other meta-information.
`/_all_dbs`	GET	`get_all_databases`	Get list of all databases.
`/db`	HEAD	`head_database`	Test whether a database exists.
	GET	`get_database`	Get meta-information about a database.
	PUT	`put_database`	Create a database.
	DELETE	`delete_database`	Delete a database.
	POST	`post_database`	Create a document.
`/db/_changes`	GET	`get_changes`	Get changes made to documents in a database.
`/db/doc` `/db/_design/design-doc` `/db/_local/id`	HEAD	`head_document`	Test whether a document exists.
	GET	`get_document`	Get meta-information and application-defined content for a document.
	PUT	`put_document`	Create or update a document.
	DELETE	`delete_document`	Delete a document.
`/db/_design/design-doc/_view/view`	GET	`get_view`	Execute a view.

Modules

action	The `action` module defines action types.
testing	Test utilities.

Structs

ChangeItem	Document leaf as returned in a change result.
ChangeItemBuilder	Builder for constructing a change item.
ChangeResult	Single element as returned in a change list.
ChangeResultBuilder	Builder for constructing a change result.
Changes	List of changes to documents within a database.
ChangesBuilder	Builder for constructing a change list.
Client	Entry point for communicating with a CouchDB server.
Database	Database meta-information, as returned from an action to GET a database.
DatabaseName	Name of a database.
DatabasePath	Path part of a URI specifying a database.
Design	Content of a design document.
DesignBuilder	Builder for constructing a design document.
DesignDocumentName	Name of a design document.
DesignDocumentPath	Path part of a URI specifying a design document.
Document	Document, including both meta-information and application-defined content.
DocumentName	Name of a document.
DocumentPath	Path part of a URI specifying a document.
EmbeddedAttachment	An embedded attachment is an attachment contained within a document.
ErrorResponse	Response content from the CouchDB server in case of error.
Revision	Revision of a document.
Root	CouchDB server information.
Vendor	CouchDB server vendor information.
ViewFunction	JavaScript `map` and `reduce` functions for a CouchDB view.
ViewFunctionBuilder	Builder for constructing a view function.
ViewName	Name of a view.
ViewPath	Path part of a URI specifying a view.
ViewResult	Response resulting from executing a view.
ViewRow	Single row contained in the response resulting from executing a view.

Enums

DocumentId	Document identifier.
Error	Principal error type.
Heartbeat	A heartbeat specifies a duration and is used to continue retrieving database changes indefinitely.
Since	A “since” value specifies an update sequence number of a database.

Traits

IntoDatabasePath	Trait for converting a type into a `DatabasePath`.
IntoDesignDocumentPath	Trait for converting a type into a `DesignDocumentPath`.
IntoDocumentPath	Trait for converting a type into a `DocumentPath`.
IntoUrl	Trait for converting a type into a URI.
IntoViewPath	Trait for converting a type into a `ViewPath`.

Type Definitions

ViewFunctionMap

Associative collection for view functions.