sochdb-grpc 0.4.1

SochDB gRPC services for cross-language clients (Thick Server / Thin Client architecture)
Documentation

sochdb-grpc

Crates.io Documentation License

SochDB gRPC Server - Production-ready gRPC services for cross-language database access. Implements the Thick Server / Thin Client architecture where business logic resides in the server, and clients connect via gRPC or IPC.

Features

  • 10 Modular Services: KV, Graph, Collection, Namespace, Context, Policy, Trace, Checkpoint, SemanticCache, MCP
  • Temporal Graph Support: Time-bounded edges with time-travel queries (POINT_IN_TIME, RANGE, CURRENT)
  • Format Utilities: LLM context optimization (TOON format: 40-66% fewer tokens than JSON)
  • Atomic Operations: Batch writes with crash-safety guarantees
  • Zero Business Logic Duplication: Single source of truth in Rust
  • Multi-Protocol: Supports both gRPC (TCP) and Unix domain sockets (IPC)

Installation

cargo install sochdb-grpc

Or add to your Cargo.toml:

[dependencies]
sochdb-grpc = "0.3.4"

Usage

Running the Server

# Start gRPC server on default port (50051)
sochdb-grpc-server

# Custom port
sochdb-grpc-server --port 8080

# Unix domain socket
sochdb-grpc-server --socket /tmp/sochdb.sock

Environment Variables

SOCHDB_LOG=debug       # Enable debug logging
SOCHDB_PORT=50051      # Server port
SOCHDB_HOST=0.0.0.0    # Bind address

Services

KvService

Key-value operations with atomic batch writes:

rpc Get(GetRequest) returns (GetResponse);
rpc Put(PutRequest) returns (PutResponse);
rpc BatchPut(BatchPutRequest) returns (BatchPutResponse);
rpc Delete(DeleteRequest) returns (DeleteResponse);
rpc Scan(ScanRequest) returns (ScanResponse);

GraphService

Temporal graph operations with time-travel queries:

rpc AddEdge(AddEdgeRequest) returns (AddEdgeResponse);
rpc AddTemporalEdge(AddTemporalEdgeRequest) returns (AddTemporalEdgeResponse);
rpc QueryGraph(QueryGraphRequest) returns (QueryGraphResponse);
rpc QueryTemporalGraph(QueryTemporalGraphRequest) returns (QueryTemporalGraphResponse);

Temporal Query Example:

use sochdb_grpc::graph_server::GraphService;

// Query: "Was door_1 open 30 minutes ago?"
let request = QueryTemporalGraphRequest {
    namespace: "agent_memory".to_string(),
    edge_type: Some("state".to_string()),
    query_mode: TemporalQueryMode::PointInTime as i32,
    timestamp: (now - 30 * 60 * 1000), // 30 mins ago
};

let response = graph_service.query_temporal_graph(request).await?;

CollectionService

Vector search and embedding operations:

rpc CreateCollection(CreateCollectionRequest) returns (CreateCollectionResponse);
rpc Insert(InsertRequest) returns (InsertResponse);
rpc Search(SearchRequest) returns (SearchResponse);
rpc Delete(DeleteRequest) returns (DeleteResponse);

NamespaceService

Namespace isolation for multi-tenancy:

rpc CreateNamespace(CreateNamespaceRequest) returns (CreateNamespaceResponse);
rpc ListNamespaces(ListNamespacesRequest) returns (ListNamespacesResponse);
rpc DeleteNamespace(DeleteNamespaceRequest) returns (DeleteNamespaceResponse);

ContextService

LLM context formatting and optimization:

rpc FormatContext(FormatContextRequest) returns (FormatContextResponse);
rpc ConvertWireFormat(ConvertWireFormatRequest) returns (ConvertWireFormatResponse);

Format Benefits:

  • TOON Format: 40-66% fewer tokens than JSON → Lower LLM API costs
  • Columnar Format: Efficient for tabular data
  • Round-trip Safe: Lossless conversions

PolicyService, TraceService, CheckpointService, SemanticCacheService

Advanced features for production deployments:

  • Access control policies
  • Query tracing and debugging
  • Database checkpointing
  • Semantic caching for LLM queries

McpService

Model Context Protocol integration for agent workflows.

Architecture

Thick Server / Thin Client:

  • ✅ Business logic in Rust (single source of truth)
  • ✅ Zero code duplication across SDKs
  • ✅ O(1) maintenance model
  • ✅ Multi-language support (Python, Node.js, Go)

Dual-Mode Access:

  • Server Mode (gRPC): Production deployments with centralized logic
  • Embedded Mode (FFI): Local development and edge deployments

Protocol Buffers

Proto definitions available at: proto/sochdb.proto

Generate clients:

# Python
python -m grpc_tools.protoc -I./proto --python_out=. --grpc_python_out=. proto/sochdb.proto

# Node.js
npm install @grpc/grpc-js @grpc/proto-loader
grpc_tools_node_protoc --js_out=import_style=commonjs,binary:. --grpc_out=grpc_js:. proto/sochdb.proto

# Go
protoc --go_out=. --go-grpc_out=. proto/sochdb.proto

Performance

  • Request Throughput: ~50K ops/sec (batch_put)
  • Latency: <1ms P50, <5ms P99 (local)
  • Memory: ~10MB baseline + ~100 bytes per connection
  • Connections: Supports 10K+ concurrent clients

Development

# Build
cd sochdb-grpc
cargo build --release

# Run with debug logging
RUST_LOG=debug cargo run -- --port 50051

# Test
cargo test

Contributing

See CONTRIBUTING.md

License

Apache-2.0

Links

Version

Current: 0.3.4

What's New in 0.3.4:

  • ✨ Temporal graph support with time-travel queries
  • ✨ Format utilities for LLM context optimization (40-66% token savings)
  • ✨ Enhanced gRPC service architecture (10 modular services)
  • ✨ Atomic batch operations with crash-safety
  • 🔧 Zero business logic duplication across SDKs
  • 📚 Comprehensive SDK documentation (Python, Node.js, Go)