ONQL Rust Driver

Official Rust client for the ONQL database server.

Installation

From crates.io

[dependencies]
onql-client = "0.1"

From GitHub (latest main)

[dependencies]
onql-client = { git = "https://github.com/ONQL/onqlclient-rust" }

Pinned to a release tag

[dependencies]
onql-client = { git = "https://github.com/ONQL/onqlclient-rust", tag = "v0.1.0" }

Quick Start

use onql_client::ONQLClient;#[tokio::main]asyncfnmain() -> Result<(),Box<dyn std::error::Error>>{let client = ONQLClient::connect("localhost",5656).await?;
client.insert("mydb","users",&serde_json::json!({"id":"u1","name":"John","age":30})).await?;let rows = client.onql("mydb.users[age>18]").await?;println!("{rows}");let q = ONQLClient::build("mydb.users[id=$1].id",&[serde_json::json!("u1")]);
client.update("mydb","users",&serde_json::json!({"age":31}),&q).await?;
client.delete_with::<&str>("mydb","users","","default",&["u1"]).await?;
client.close().await?;Ok(())}

API Reference

ONQLClient::connect(host, port) -> Result<ONQLClient>

Creates and returns a connected client.

client.send_request(keyword, payload) -> Result<Response>

Sends a raw request frame and waits for a response.

client.close() -> Result<()>

Closes the connection.

Direct ORM-style API

On top of raw send_request, the client exposes convenience methods for the insert / update / delete / onql operations. Each one builds the standard payload envelope for you and unwraps the {error, data} response — returning an Err(Error::Protocol) on a non-empty error field, or the decoded data (a serde_json::Value) on success.

db is passed explicitly to insert / update / delete. onql takes a fully-qualified ONQL expression.

query arguments are ONQL expression strings, e.g. mydb.users[id="u1"].id.

client.insert(db, table, data) -> Result<serde_json::Value>

Insert a single record. data is any serde::Serialize.

use serde::Serialize;#[derive(Serialize)]structUser{id:String,name:String,age:u32}
client.insert("mydb","users",&User{id:"u1".into(),name:"John".into(),age:30}).await?;

client.update(db, table, data, query) / client.update_with(db, table, data, query, protopass, ids)

Update records matching query (or ids).

client.update("mydb","users",&serde_json::json!({"age":31}),"mydb.users[id=\"u1\"].id").await?;
client.update_with::<_,&str>("mydb","users",&serde_json::json!({"age":31}),"","default",&["u1"]).await?;

client.delete(db, table, query) / client.delete_with(db, table, query, protopass, ids)

Delete records matching query (or ids).

client.delete("mydb","users","mydb.users[id=\"u1\"].id").await?;
client.delete_with::<&str>("mydb","users","","default",&["u1"]).await?;

client.onql(query) / client.onql_with(query, protopass, ctxkey, ctxvalues)

Run a raw ONQL query.

let rows = client.onql("mydb.users[age>18]").await?;

ONQLClient::build(query, values) -> String

Replace $1, $2, … placeholders with serde_json::Values.

let q = ONQLClient::build("mydb.users[name=$1 and age>$2]",&[serde_json::json!("John"), serde_json::json!(18)],);let rows = client.onql(&q).await?;

ONQLClient::process_result(raw) -> Result<serde_json::Value>

Static helper that parses the {error, data} envelope.

Protocol

<request_id>\x1E<keyword>\x1E<payload>\x04

• \x1E — field delimiter
• \x04 — end-of-message marker

License

MIT