Native Driver Protocol

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

Connection Handshake

When connecting, the client must send the magic header:

solidb-drv-v1\0  (14 bytes)

Message Format

Each message consists of:

1. Length: 4 bytes, big-endian unsigned integer
2. 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).

Query Timeout

Query and Explain are capped at 30 seconds, the same limit the HTTP /cursor endpoint applies. Point reads run inline; anything that scans, loops, or mutates runs on the blocking pool under the cap. Overrunning it returns a DatabaseError reading Query execution timeout: exceeded 30 seconds. Note that a mutation which overruns still commits — the executor cannot be cancelled mid-write — so treat the timeout as "the result is unavailable", not "the write did not happen".

TLS

The driver protocol is plaintext. None of the shipped SDKs negotiate TLS before sending the magic header, so run the driver port on a trusted network or tunnel it yourself.

Starting the server with --tls-cert / --tls-key does not break this: on a multiplexed port the listener sniffs for a TLS ClientHello and only handshakes when a client offers one, so plaintext driver connections are passed through untouched. Setting SOLIDB_TLS_REQUIRE=1 does refuse them — do not set it on a node that serves driver clients. See Transport Security.

Utility Commands

Database Operations

Collection Operations

Document Operations

Query Operations

Transaction Operations

Bulk Operations

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": "alice@example.com"
    })).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?;

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

Errors are returned with type-specific error codes: