Crate couch_rs

CouchDB library for Rust

Description

This crate is an interface to CouchDB HTTP REST API. Works with stable Rust.

This library is a spin-off based on the excellent work done by Mathieu Amiot and others at Yellow Innovation on the Sofa library. The original project can be found at https://github.com/YellowInnovation/sofa

The Sofa library lacked support for async I/O, and missed a few essential operations we needed in our projects. That’s why I’ve decided to create a new project based on the original Sofa code.

The rust-rs library has been updated to the Rust 2021 edition standards, uses async I/O, and compiles against the latest serde and reqwest libraries.

NOT 1.0 YET, so expect changes

Supports CouchDB 2.3.0 and up. Used in production with various CouchDB versions, including 3.4.1

Be sure to check CouchDB’s Documentation in detail to see what’s possible.

Example code

You can launch the included example with:

cargo run --example basic_operations

Running tests

Make sure that you have an instance of CouchDB 2.0+ running, either via the supplied docker-compose.yml file or by yourself. It must be listening on the default port. Since Couch 3.0 the “Admin Party” mode is no longer supported. This means you need to provide a username and password during launch. The tests and examples assume an “admin” CouchDB user with a “password” CouchDB password. Docker run command:

docker run --rm -p 5984:5984 -e COUCHDB_USER=admin -e COUCHDB_PW=password couchdb:3

And then cargo test -- --test-threads=1

Single-threading the tests is very important because we need to make sure that the basic features are working before actually testing features on dbs/documents.

Usage

A typical find operation looks like this.

use couch_rs::types::find::FindQuery;
use std::error::Error;
use serde_json::Value;
use couch_rs::document::DocumentCollection;

const DB_HOST: &str = "http://localhost:5984";
const TEST_DB: &str = "test_db";

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let client = couch_rs::Client::new(DB_HOST, "admin", "password")?;
    let db = client.db(TEST_DB).await?;
    let find_all = FindQuery::find_all();
    let docs = db.find_raw(&find_all).await?;
    Ok(())
}

You can use a similar operation to get a typed Couch document.

use couch_rs::CouchDocument;
use couch_rs::types::find::FindQuery;
use couch_rs::document::{DocumentCollection, TypedCouchDocument};
use couch_rs::types::document::DocumentId;
use std::error::Error;
use serde_json::Value;
use serde::{Deserialize, Serialize};

const DB_HOST: &str = "http://localhost:5984";
const TEST_DB: &str = "user_db";

#[derive(Serialize, Deserialize, CouchDocument)]
pub struct UserDetails {
   #[serde(skip_serializing_if = "String::is_empty")]
    pub _id: DocumentId,
    #[serde(skip_serializing_if = "String::is_empty")]
    pub _rev: String,
    #[serde(rename = "firstName")]
    pub first_name: Option<String>,
    #[serde(rename = "lastName")]
    pub last_name: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let client = couch_rs::Client::new(DB_HOST, "admin", "password")?;
    let db = client.db(TEST_DB).await?;
    let find_all = FindQuery::find_all();
    let docs: DocumentCollection<UserDetails> = db.find(&find_all).await?;
    Ok(())
}

See the database module for additional usage examples. Or have a look at the examples in the GitHub repositiory.

The typed module provides a typed wrapper around Database where all operations are performed on a specific generic type. This is useful when you want to work with a specific type of document for all operations on a database insteance as the compiler will flag any errors at compile time if different types are mixed using the same database instance.

Re-exports

pub use http;

Modules

database

Database operations on a CouchDB Database.

document

Document model to support CouchDB document operations.

error

Error wrappers for the HTTP status codes returned by CouchDB.

management

Data types to support CouchDB management operations

model

Trait that provides methods that can be used to switch between abstract Document and concrete Model implementors (such as your custom data models)

typed

Typed Database operations on a CouchDB Database.

types

Data types to support CouchDB operations.

Macros

find_all_selector

Returns all documents

Structs

Client

Client handles the URI manipulation logic and the HTTP calls to the CouchDB REST API. It is also responsible for the creation/access/destruction of databases.

Enums

Cow

A clone-on-write smart pointer.