Expand description
A lightweight gRPC client for ArcadeDB.
Generated tonic stubs for com.arcadedb.grpc, a typed record-decode path
(RecordDecode derive + runtime), a serde_json bridge for dynamic
access, and nothing else.
§What’s here
client::ArcadeDbClient— wraps the data + admin gRPC services (connect with retry, auth headers,execute/query/create_database/bulk_insert, …).Clone(shares one tonicChannel).error::ArcadeDbError— the typed error for every fallible client call: match on the failure category (transport, server-rejected command, decode, invalid input) and inspect the gRPC code/metadata.- JSON bridge (
grpc_record_to_json):GrpcRecord→serde_json::Valuefor callers that need dynamic access. The typed decode path isRecordDecode(see below) — there is no serdeDeserializeranymore. record— the typed-decode runtime:record::FromGrpcValue,record::RecordDecodeError, and the property-access helpers used by the generated code.RecordDecode(re-exported derive) —#[derive(RecordDecode)]turns a model struct intoTryFrom<&GrpcRecord>+FromGrpcValuewith per-field type coercion, honoring#[serde(rename/default/flatten)]for drop-in adoption. Custom types plug in via the#[record(with = “…”)]attribute or by implementingFromGrpcValue` directly.RecordEncode(re-exported derive) — the write-side mirror: derivesrecord::ToGrpcRecordso bulk writers calldto.to_grpc_record(class)instead of hand-assemblingGrpcValue/GrpcRecordprotos.- Value builders (
Params,IntoGrpcValue) for fixture/test code.
§Optional features
ahash— aHash maps as first-class wire maps:ahash::AHashMap<String, V>binds as the wireMap(encode) and decodes back into anAHashMap(decode), so a DTO field or aparams!value can be an aHash map with no std↔aHash conversion.cache— transient KV facade over the Redis plugin (client.cache()).decimal— exactrust_decimal::Decimalmapping forDECIMALcolumns.fxhash— rustc’s FxHash maps as first-class wire maps (rustc_hash::FxHashMap<String, V>), same as theahashfeature.rayon— parallel decode of large batches.serde— serde impls for wire-identity types (Link↔ rid string).
§What’s NOT here
Identity types and query/repository layers. ArcadeDB’s native RID
(#bucket:pos) is the only identifier this crate deals with; apps choose
their own logical identity scheme (e.g. table:key or an external id)
and build their repo + query functions on top of ArcadeDbClient.
use arcadedb_protocol::ArcadeDbClient;
let client = ArcadeDbClient::connect("127.0.0.1:50051", "root", "password", "mydb").await?;
let res = client.query("mydb", "SELECT FROM item LIMIT 10").await?;
println!("{} rows in {} ms", res.len(), res.execution_time_ms);Re-exports§
pub use batch::Batch;pub use batch::ScriptBuffer;pub use client::consume_stream;pub use client::ArcadeDbClient;pub use client::DatabaseClient;pub use client::QueryResult;pub use client::QueryResultBatch;pub use client::StreamSummary;pub use client::Transaction;pub use client::TxCommands;pub use options::ClientOptions;pub use stream::StreamOptions;pub use error::ArcadeDbError;pub use error::Result;pub use proto::com::arcadedb::grpc::GrpcRecord;pub use proto::com::arcadedb::grpc::GrpcEmbedded;pub use proto::com::arcadedb::grpc::GrpcLink;pub use proto::com::arcadedb::grpc::GrpcList;pub use proto::com::arcadedb::grpc::GrpcMap;pub use proto::com::arcadedb::grpc::GrpcValue;pub use proto::com::arcadedb::grpc::grpc_value::Kind;pub use record::changed_param_map;pub use record::from_map_via_value;pub use record::props_diff;pub use record::DecodeFromMap;pub use record::FromGrpcValue;pub use record::Link;pub use record::RecordDecodeError;pub use record::ToGrpcRecord;pub use proto::com::arcadedb::grpc::arcade_db_admin_service_client::ArcadeDbAdminServiceClient;pub use proto::com::arcadedb::grpc::arcade_db_service_client::ArcadeDbServiceClient;pub use proto::com::arcadedb::grpc::ExecuteCommandResponse;pub use proto::com::arcadedb::grpc::InsertSummary;
Modules§
- admin
- Admin operations — the
ArcadeDbClient::adminfacade. - batch
- Multi-statement units — the
ArcadeDbClient::batchfacade. - error
- The client-facing error type: every fallible
ArcadeDbClient/DatabaseClientcall returnsResult<T, ArcadeDbError>instead of an opaque error. Matching on the failure category distinguishes transport vs. server-rejected vs. decode vs. client-side validation errors, and the gRPCtonic::Codestays inspectable. - options
- Connection configuration: the
ClientOptionsbuilder. - proto
- record
- Typed record decoding — the runtime behind
crate::RecordDecode. - scan
- Full-type/bucket iteration — the
ArcadeDbClient::scanfacade. - stream
- Streaming query options — the
ArcadeDbClient::stream_query_with_optionsbuilder. - testutil
- Throwaway test databases for suites running against a live server.
Macros§
- embedded
- Assemble an embedded record value — the nestable, value-form sibling
of
rec: samekey: valueentry grammar asparams!, each field dispatching its ownIntoGrpcValue, producing the wire’s embedded (Kind::EmbeddedValue) shape. Values nest and compose:vec![embedded!(..), ..]is a list of embedded values, and a built value rides anywhere a value does (recfields,params!,SetClause) through theGrpcValuepass-through. - impl_
decode_ from_ map_ via_ value - Implement
DecodeFromMapfor a manualFromGrpcValuetype through the clone-basedfrom_map_via_valuepath — for manual types used as#[serde(flatten)]targets. Prefer derivingRecordDecodeon flatten targets (zero-copy). - params
- Assemble bound parameters with map semantics — the literal form for the
client’s
*_with_valuesmethods. - sql
sql!— write the statement as a literal, get a syntax check for free.
Structs§
- Arcade
DbClient - A lightweight gRPC client for ArcadeDB.
- Database
Client - An
ArcadeDbClientbound to one database: every delegated method drops thedatabase: &strparameter. The connect-time name is the single source of truth, which removes the per-call-site repetition and the wrong-db mistake class. - Filter
Clause - Accumulates AND-joined WHERE fragments and their bound values.
- Params
- Bound-parameter map for the client’s
*_with_values/execute_with_valuesmethods. Construct it from an array literal (the common case) or wrap an existing map / a RecordEncode DTO’sToGrpcRecord::to_param_mapoutput. - Query
Result - The result of a SQL query, bundling the returned records with server-side execution timing.
- SetClause
- Accumulates
col = :colSET fragments and their bound values forINSERT INTO … SET …/UPDATE … SET …statements whose shape is only known at runtime (optional fields, conditional writes). - Stream
Summary - Accounting for a consumed
StreamQuerystream. - Timestamp
- The protobuf well-known
Timestamp— the wire shape for date/datetime values (Kind::TimestampValue), re-exported forRecordEncodeDTOs. A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. - Transaction
- A drop-safe explicit transaction: the guard returned by
ArcadeDbClient::transaction. Commands run through the guard; finishing is explicit (commit/rollbackboth consumeself), and a guard dropped unfinished rolls back in a background task — the server’s idle-reaper is the last line of defense. - TxCommands
- Commands issued inside
ArcadeDbClient::run_transaction’s current attempt — theTransactionguard’s operations without the lifecycle (begin/commit/rollback are the runner’s job).
Traits§
- Into
Grpc Value - The encode-side mirror of
crate::record::FromGrpcValue: Rust values convert to their natural wire kind, soparams!can accept computed expressions and let trait resolution pick the constructor.
Functions§
- consume_
stream - Consume a
StreamQuerybatch stream throughon_batch, one batch at a time. This is the testable core ofArcadeDbClient::stream_query: generic over any stream of proto batches, so tests drive it with fakes instead of a live server. - grpc_
record_ to_ json - Convert a record’s properties into a JSON object.
- grpc_
value_ to_ json - Convert a single typed value.
Nonekind -> null. - json_
to_ grpc_ value - Convert a
serde_jsonvalue onto the matching wire kind — the inverse ofgrpc_value_to_json, enabling dynamic (schemaless) ENCODE paths:serde_json::ValueDTO fields, API-request payloads bound as:params. - rec
- Build a record of
type_namefrom(field, value)pairs — values go throughIntoGrpcValue, same coverage asparams!(no constructor ceremony at call sites; already-convertedGrpcValues pass through).ridis left empty (the server assigns it on insert).
Derive Macros§
- Record
Decode #[derive(RecordDecode)].- Record
Encode #[derive(RecordEncode)]— the encode-side mirror ofRecordDecode: generatesToGrpcRecord(see the module docs for the attribute reference).