2 releases

Uses old Rust 2015

0.1.1 May 31, 2018
0.1.0 Apr 15, 2018

#2738 in Database interfaces


Used in 4 crates (2 directly)

Apache-2.0

585KB
14K SLoC

Rincon Client

Crates.io Docs.rs Apache-2.0 Join the chat

Type safe interaction with the ArangoDB REST API

The rincon_client crate provides types and functions to interact with the REST API of the ArangoDB server.

In rincon_client the REST methods are represented by structs. A method is instantiated with the desired parameters and data to get a method call. The method call is executed against an ArangoDB server on a connection provided by a connector. This concept allows applications to queue, distribute or batch process method calls.

For example, inserting a new document into an existing collection looks like:

#[derive(Debug, Clone, Serialize, Deserialize)]
struct Customer {
    name: String,
    age: u8,
}

let customer = Customer {
    name: "Jane Doe".to_owned(),
    age: 42,
};

// create a new document with the customer struct as content
let new_document = NewDocument::from_content(customer);

// create the method call to insert new_document into the 'customers' collection.
let method = InsertDocument::new("customers", new_document);

// execute the method call
let document = core.run(connection.execute(method)).unwrap();

The REST API of ArangoDB comprises a lot of methods. An overview of the currently implemented methods can be found here.

The rincon_client crate is part of the Rincon ArangoDB Rust driver project.

Usage

Crate Features

The rincon_client crate can be compiled with optional features to adapt to the configuration of the ArangoDB server to be used. These optional features support attributes on the method calls and their results that are specific to the related ArangoDB configuration.

The provided crate features are:

  • mmfiles : support for MMFiles storage engine specific attributes (optional)
  • rocksdb : support for RocksDB storage engine specific attributes (optional)
  • cluster : support for cluster specific attributes (optional)
  • enterprise : support for ArangoDB enterprise specific attributes (optional)

Note1: A deployed ArangoDB server uses either MMFiles or RocksDB storage engine. Therefore only one of the features mmfiles and rocksdb features may be activated, but not both.

Note2: If rincon_client is compiled with the cluster feature some API methods which return cluster specific fields do not work with an ArangoDB server that is not configured in a cluster. This is due to the ArangoDB server does not return cluster specific fields in a single server configuration.

It is not necessary to activate any of the optional crate features if an application does not need to access the feature related attributes.

Examples

Using MMFiles storage engine

If you want to make use of the MMFiles related attributes and the ArangoDB server is configured to use the MMFiles storage engine, rincon_client can be compiled with the mmfiles feature to support MMFiles specific attributes and fields within the API methods.

[dependencies]
rincon_client = { version = "0.1", features = ["mmfiles"] }

Using RocksDB storage engine

If the ArangoDB server is configured to use the RocksDB storage engine, rincon_client can be compiled with the rocksdb feature to support RocksDB specific attributes and fields within the API methods.

[dependencies]
rincon_client = { version = "0.1", features = ["rocksdb"] }

Using an ArangoDB Cluster

To use the ArangoDB cluster specific features of the API, rincon_client must be compiled with the cluster feature enabled.

[dependencies]
rincon_client = { version = "0.1", features = ["cluster"] }

Using ArangoDB Enterprise features

To add support for ArangoDB enterprise features in the client API add this to your dependencies:

[dependencies]
rincon_client = { version = "0.1", features = ["enterprise"] }

Using an ArangoDB Cluster with Enterprise features

The optional features may be combined, but only one storage engine feature may be enabled at a time.

To use enterprise, cluster and MMFiles specific features add this to your dependencies:

[dependencies]
rincon_client = { version = "0.1", features = ["mmfiles", "enterprise", "cluster"] }

To use enterprise, cluster and RocksDB specific features add this to your dependencies:

[dependencies]
rincon_client = { version = "0.1", features = ["rocksdb", "enterprise", "cluster"] }

Connector and core types

In any case we also need a connector like one provided by the rincon_connector crate and some types defined in the rincon_core crate. This means we need to add additional dependencies:

[dependencies]
rincon_core = "0.1"
rincon_connector = "0.1"
# plus dependency as explained above
rincon_client = "0.1" 

License

Licensed under Apache License, Version 2.0
see LICENSE or http://www.apache.org/licenses/LICENSE-2.0 for details.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.

Dependencies

~6.5MB
~169K SLoC