Database API Reference

The Database struct is the primary entry point for all RouchDB operations. It wraps any Adapter implementation behind an Arc<dyn Adapter>, providing a high-level API similar to PouchDB’s JavaScript interface.

#![allow(unused)]
fn main() {
use rouchdb::Database;
}

Constructors

Examples

#![allow(unused)]
fn main() {
// In-memory (for tests)
let db = Database::memory("mydb");

// Persistent (redb file)
let db = Database::open("path/to/mydb.redb", "mydb")?;

// Remote CouchDB
let db = Database::http("http://localhost:5984/mydb");
}

Document Operations

These methods correspond to CouchDB’s core document API. See the Core Types Reference for details on the option and response structs.

Examples

#![allow(unused)]
fn main() {
// Post (auto-generated ID)
let result = db.post(json!({"name": "Alice", "age": 30})).await?;
println!("Generated ID: {}", result.id);

// Put (explicit ID)
let result = db.put("user:alice", json!({"name": "Alice", "age": 30})).await?;
let doc = db.get("user:alice").await?;

// Update (requires current rev)
let updated = db.update("user:alice", &result.rev.unwrap(), json!({"name": "Alice", "age": 31})).await?;

// Delete
db.remove("user:alice", &updated.rev.unwrap()).await?;

// Bulk write
let docs = vec![
    Document { id: "a".into(), rev: None, deleted: false, data: json!({}), attachments: HashMap::new() },
    Document { id: "b".into(), rev: None, deleted: false, data: json!({}), attachments: HashMap::new() },
];
let results = db.bulk_docs(docs, BulkDocsOptions::new()).await?;

// All docs with options
let response = db.all_docs(AllDocsOptions {
    include_docs: true,
    limit: Some(10),
    ..AllDocsOptions::new()
}).await?;
}

Attachment Operations

Example

#![allow(unused)]
fn main() {
// Put attachment
let att_result = db.put_attachment("doc1", "photo.jpg", &rev, data, "image/jpeg").await?;

// Get attachment
let bytes = db.get_attachment("doc1", "photo.jpg").await?;

// Remove the attachment
let rm = db.remove_attachment("doc1", "photo.jpg", &att_result.rev.unwrap()).await?;
}

Query Operations

Example

#![allow(unused)]
fn main() {
let result = db.find(FindOptions {
    selector: json!({"age": {"$gte": 21}}),
    fields: Some(vec!["name".into(), "age".into()]),
    sort: Some(vec![SortField::Simple("age".into())]),
    limit: Some(25),
    ..Default::default()
}).await?;

for doc in &result.docs {
    println!("{}", doc);
}
}

Index Operations

Example

#![allow(unused)]
fn main() {
use rouchdb::{IndexDefinition, SortField};

// Create an index on the "age" field
let result = db.create_index(IndexDefinition {
    name: String::new(), // auto-generated as "idx-age"
    fields: vec![SortField::Simple("age".into())],
    ddoc: None,
}).await?;
println!("Index: {} ({})", result.name, result.result);

// Queries on "age" now use the index instead of a full scan
let found = db.find(FindOptions {
    selector: json!({"age": {"$gte": 21}}),
    ..Default::default()
}).await?;

// List indexes
let indexes = db.get_indexes().await;

// Delete an index
db.delete_index("idx-age").await?;
}

Replication

All replication methods implement the CouchDB replication protocol: checkpoint reading, changes feed, revision diff, bulk document fetch, and checkpoint saving. See the Replication chapter for a conceptual overview.

ReplicationOptions

ReplicationFilter

ReplicationResult

Example

#![allow(unused)]
fn main() {
let local = Database::open("local.redb", "mydb")?;
let remote = Database::http("http://localhost:5984/mydb");

// Push local changes to CouchDB
let push = local.replicate_to(&remote).await?;
println!("Pushed {} docs", push.docs_written);

// Full bidirectional sync
let (push, pull) = local.sync(&remote).await?;
}

Query Planning

Example

#![allow(unused)]
fn main() {
let explanation = db.explain(FindOptions {
    selector: serde_json::json!({"age": {"$gt": 20}}),
    ..Default::default()
}).await;

println!("Index: {} ({})", explanation.index.name, explanation.index.index_type);
}

Design Document Operations

See the Design Documents & Views guide for details.

Security

Changes Feed (Event-Based)

See the Changes Feed guide for details.

Partitioned Queries

The returned Partition supports get(), put(), all_docs(), and find(). See the Partitioned Databases guide.

Plugin System

See the Plugins guide for details.

Maintenance

Accessing the Adapter

Example

#![allow(unused)]
fn main() {
let db = Database::memory("test");

// Access adapter directly for replication-level operations
let diff = db.adapter().revs_diff(rev_map).await?;
let local = db.adapter().get_local("_local/my-checkpoint").await?;
}