# GitDB Rust Client
Official Rust client for GitDB - GitHub-backed NoSQL database.
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
gitdb-client = "1.0.0"
```
## Quick Start
```rust
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
```rust
// 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
```rust
// Check if server is healthy
client.health().await?;
```
### Collection Management
```rust
// 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
```rust
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
```rust
// 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
```rust
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
```rust
// 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
```rust
// 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
```rust
// 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:
```rust
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:
```rust
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:
```bash
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:
```rust
let client = GitDBClient::with_url(token, owner, repo, base_url);
client.set_base_url("http://custom-server:7896");
```
## Testing
Run the tests:
```bash
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