CouchDB library for Rust

Documentation

Here: http://docs.rs/couch_rs

Installation

Include this dependency in the Cargo.toml file:

[dependencies]
couch_rs = "0.13"

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.

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(())
}

Examples

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_PASSWORD=password couchdb:3

And then cargo test --features=integration-tests -- --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.

If bash is available on your environment, you can also use the test.sh script which basically does the same thing described above.

TLS Backend

By default, couch_rs uses rustls as the TLS backend for reqwest. This provides a pure Rust implementation that works across platforms without requiring system TLS libraries.

Switching to native-tls

If you need to use the system's native TLS implementation instead (for example, to support system certificate stores or for compatibility with certain corporate proxy configurations), you can disable the default features and explicitly enable native-tls:

[dependencies]
couch_rs = { version = "0.13", default-features = false, features = ["derive", "native-tls"] }

Available TLS feature options (choose one):

• rustls-tls (default) - Uses rustls, a pure Rust TLS implementation
• native-tls - Uses the platform's native TLS library (OpenSSL on Linux, Secure Transport on macOS, SChannel on Windows)
• native-tls-vendored - Same as native-tls, but compiles and statically links OpenSSL
• native-tls-alpn - Native TLS with ALPN support
• rustls-no-provider - rustls without a default crypto provider (for advanced use cases)

Note: When using default-features = false, make sure to re-enable the derive feature if you want to use the #[derive(CouchDocument)] macro.

License

Licensed under either of these:

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

DISCLAIMER

Please note: all content in this repository is released for use "AS IS" without any warranties of any kind, including, but not limited to their installation, use, or performance. We disclaim any and all warranties, either express or implied, including but not limited to any warranty of noninfringement, merchantability, and/ or fitness for a particular purpose. We do not warrant that the technology will meet your requirements, that the operation thereof will be uninterrupted or error-free, or that any errors will be corrected.

Any use of this library is at your own risk. There is no guarantee that it has been through thorough testing in a comparable environment and we are not responsible for any damage or data loss incurred with their use.

You are responsible for reviewing and testing any code you run thoroughly before use in any non-testing environment.