GitDB Rust Client

Official Rust client for GitDB - GitHub-backed NoSQL database.

Installation

Add this to your Cargo.toml:

[dependencies]
gitdb-client = "1.0.0"

Quick Start

use gitdb_client::GitDBClient;
use std::collections::HashMap;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize client
    let client = GitDBClient::new(
        "your-github-token",
        "your-github-username", 
        "your-repo-name"
    );
    
    // Check server health
    client.health().await?;
    
    // Create a collection
    client.create_collection("users").await?;
    
    // Insert a document
    let mut user = HashMap::new();
    user.insert("name".to_string(), json!("John Doe"));
    user.insert("email".to_string(), json!("john@example.com"));
    user.insert("age".to_string(), json!(30));
    
    let id = client.insert("users", &user).await?;
    println!("Inserted user with ID: {}", id);
    
    // Find documents
    let mut query = HashMap::new();
    query.insert("age".to_string(), json!({ "$gte": 25 }));
    
    let users = client.find("users", &query).await?;
    println!("Found {} users", users.len());
    
    // Update a document
    let mut update = HashMap::new();
    update.insert("age".to_string(), json!(31));
    
    client.update("users", &id, &update).await?;
    println!("Updated user");
    
    // Delete a document
    client.delete("users", &id).await?;
    println!("Deleted user");
    
    Ok(())
}

Features

• ✅ Zero-cost abstractions - High performance with minimal overhead
• ✅ Memory safety - Rust's ownership system prevents common bugs
• ✅ Async/await support - Non-blocking operations with tokio
• ✅ Type safety - Strong typing throughout the API
• ✅ Error handling - Comprehensive error handling with anyhow
• ✅ CRUD operations - Create, Read, Update, Delete documents
• ✅ Query support - MongoDB-style query operators
• ✅ GraphQL integration - Native GraphQL query support
• ✅ Batch operations - Insert, update, delete multiple documents
• ✅ Collection management - Create, list, delete collections

API Reference

Client Creation

// Basic client
let client = GitDBClient::new(token, owner, repo);

// Client with custom URL
let client = GitDBClient::with_url(token, owner, repo, "http://localhost:7896");

Health Check

// Check if server is healthy
client.health().await?;

Collection Management

// Create a collection
client.create_collection("users").await?;

// List all collections
let collections = client.list_collections().await?;
for collection in collections {
    println!("Collection: {} ({} documents)", collection.name, collection.count);
}

// Delete a collection
client.delete_collection("users").await?;

Document Operations

Insert

let mut document = HashMap::new();
document.insert("name".to_string(), json!("Alice"));
document.insert("age".to_string(), json!(25));

let id = client.insert("users", &document).await?;

Find

// Find all documents
let all_users = client.find("users", &HashMap::new()).await?;

// Find with query
let mut query = HashMap::new();
query.insert("age".to_string(), json!({ "$gte": 30 }));
let older_users = client.find("users", &query).await?;

// Find one document
let user = client.find_one("users", &query).await?;

// Find by ID
let user = client.find_by_id("users", "document-id").await?;

Update

let mut update = HashMap::new();
update.insert("age".to_string(), json!(26));
update.insert("last_updated".to_string(), json!("2024-01-01"));

client.update("users", "document-id", &update).await?;

Delete

// Delete by ID
client.delete("users", "document-id").await?;

// Delete multiple documents
let mut query = HashMap::new();
query.insert("age".to_string(), json!({ "$lt": 18 }));
let deleted_count = client.delete_many("users", &query).await?;

Batch Operations

// Insert multiple documents
let mut documents = Vec::new();
for i in 1..=5 {
    let mut doc = HashMap::new();
    doc.insert("name".to_string(), json!(format!("User {}", i)));
    doc.insert("age".to_string(), json!(20 + i));
    documents.push(doc);
}

for doc in documents {
    client.insert("users", &doc).await?;
}

// Update multiple documents
let mut query = HashMap::new();
query.insert("age".to_string(), json!({ "$gte": 25 }));

let mut update = HashMap::new();
update.insert("category".to_string(), json!("senior"));

let updated_count = client.update_many("users", &query, &update).await?;

GraphQL Queries

// Simple GraphQL query
let query = r#"
    query {
        users {
            id
            name
            age
        }
    }
"#;

let response = client.graphql_simple(query).await?;
if let Some(data) = response.data {
    println!("GraphQL result: {}", data);
}

// GraphQL query with variables
let query = r#"
    query GetUser($id: String!) {
        user(id: $id) {
            id
            name
            age
        }
    }
"#;

let mut variables = HashMap::new();
variables.insert("id".to_string(), json!("user-id"));

let response = client.graphql(query, Some(variables)).await?;

Query Operators

The Rust client supports MongoDB-style query operators:

let mut query = HashMap::new();

// Equal
query.insert("age".to_string(), json!(30));

// Greater than
query.insert("age".to_string(), json!({ "$gt": 25 }));

// Greater than or equal
query.insert("age".to_string(), json!({ "$gte": 25 }));

// Less than
query.insert("age".to_string(), json!({ "$lt": 50 }));

// Less than or equal
query.insert("age".to_string(), json!({ "$lte": 50 }));

// Not equal
query.insert("age".to_string(), json!({ "$ne": 30 }));

// In array
query.insert("category".to_string(), json!({ "$in": ["admin", "user"] }));

// Not in array
query.insert("category".to_string(), json!({ "$nin": ["admin"] }));

// Regular expression
query.insert("name".to_string(), json!({ "$regex": "john", "$options": "i" }));

Error Handling

The client uses anyhow::Result for error handling:

use anyhow::Result;

async fn example() -> Result<()> {
    let client = GitDBClient::new("token", "owner", "repo");
    
    match client.health().await {
        Ok(()) => println!("Server is healthy"),
        Err(e) => eprintln!("Health check failed: {}", e),
    }
    
    Ok(())
}

Configuration

Environment Variables

You can configure the client using environment variables:

export GITDB_TOKEN="your-github-token"
export GITDB_OWNER="your-github-username"
export GITDB_REPO="your-repo-name"
export GITDB_SERVER_URL="http://localhost:7896"

Custom HTTP Client

The client uses reqwest with a 30-second timeout by default. You can customize this:

let client = GitDBClient::with_url(token, owner, repo, base_url);
client.set_base_url("http://custom-server:7896");

Testing

Run the tests:

cargo test

Examples

See the examples/ directory for more detailed examples:

• Basic usage
• Advanced queries
• GraphQL operations
• Error handling
• Batch operations

Dependencies

• reqwest - HTTP client
• tokio - Async runtime
• serde - Serialization/deserialization
• serde_json - JSON handling
• anyhow - Error handling

License

MIT License - see LICENSE file for details.

Authors

• AFOT Team team@afot.com
• karthikeyanV2K karthikeyan@afot.com

Repository

https://github.com/karthikeyanV2K/GitDB