Native Driver Protocol

SoliDB provides a high-performance native binary protocol as an alternative to the HTTP REST API. The native driver offers lower latency and higher throughput.

Port: The native driver uses the same port as the HTTP API (default: 6745) via protocol multiplexing. The server automatically detects the protocol based on the connection's magic header.

Overview

The native driver protocol provides:

Binary Protocol: Uses MessagePack for efficient serialization
Length-Prefixed Framing: Reliable message boundary detection
Full Feature Parity: Supports all database operations including SDBQL queries
Connection Multiplexing: Shares port with HTTP API
Transaction Support: Full ACID transaction support

Wire Protocol

Connection Handshake

When connecting, the client must send the magic header:

solidb-drv-v1\0  (14 bytes)

Message Format

Each message consists of:

Length: 4 bytes, big-endian unsigned integer
Payload: MessagePack-encoded command or response

+------------------+-------------------------+
| Length (4 bytes) | MessagePack Payload     |
+------------------+-------------------------+

Maximum Message Size

The maximum message size is 16 MB (16,777,216 bytes).

Commands

Utility Commands

Command	Description	Fields
ping	Ping the server	None
auth	Authenticate	database, username, password

Database Operations

Command	Description	Fields
list_databases	List all databases	None
create_database	Create a database	name
delete_database	Delete a database	name

Collection Operations

Command	Description	Fields
list_collections	List collections	database
create_collection	Create collection	database, name, collection_type
delete_collection	Delete collection	database, name
collection_stats	Get collection stats	database, name

Document Operations

Command	Description	Fields
get	Get document by key	database, collection, key
insert	Insert document	database, collection, key, document
update	Update document	database, collection, key, document, merge
delete	Delete document	database, collection, key
list	List documents	database, collection, limit, offset

Query Operations

Command	Description	Fields
query	Execute SDBQL query	database, sdbql, bind_vars
explain	Explain query plan	database, sdbql, bind_vars

Transaction Operations

Command	Description	Fields
begin_transaction	Start transaction	database, isolation_level
commit_transaction	Commit transaction	tx_id
rollback_transaction	Rollback transaction	tx_id

Bulk Operations

Command	Description	Fields
batch	Execute multiple commands	commands
bulk_insert	Insert multiple documents	database, collection, documents

Rust Client Library

SoliDB includes a native Rust client library for easy integration:

Installation

Add the library to your Cargo.toml:

[dependencies]
solidb = { version = "0.1.0" }

Basic Usage

Import the client and connect to your SoliDB instance:

use solidb::driver::SoliDBClient;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box> {
    // Connect to SoliDB
    let mut client = SoliDBClient::connect("localhost:6745").await?;
    
    // Authenticate (optional)
    client.auth("mydb", "admin", "password").await?;
    
    // Insert a document
    let doc = client.insert("mydb", "users", None, json!({
        "name": "Alice",
        "email": "[email protected]"
    })).await?;
    
    println!("Inserted: {:?}", doc);
    
    // Query using SDBQL
    let results = client.query("mydb", "FOR u IN users RETURN u", None).await?;
    println!("Results: {:?}", results);
    
    Ok(())
}

Transactions

use solidb_client::protocol::IsolationLevel;

// Begin transaction
let tx_id = client.begin_transaction("mydb", Some(IsolationLevel::ReadCommitted)).await?;

// Operations are automatically associated with the transaction
client.insert("mydb", "users", None, json!({"name": "Bob"})).await?;

// Commit
client.commit().await?;

// Or rollback
// client.rollback().await?;

Performance

The native driver offers significant performance improvements over HTTP:

• ~50% lower latency due to binary protocol and no HTTP overhead
• ~30% smaller payload sizes with MessagePack vs JSON
• Persistent connections eliminate connection setup overhead

Error Handling

Errors are returned with type-specific error codes:

connection_error Network or connection issues

auth_error Authentication failed

database_error Database operation failed

transaction_error Transaction operation failed

protocol_error Protocol violation

message_too_large Message exceeds 16MB limit